Add auto-generated index to knowledge base

[Qard]

This a quick pass at auto-generating a list of links to the knowledge base pages supplied in #211. I might also try grouping links into sections based on the tags data. Thoughts?

[fhemberger]

You can use collections for that:

.use(collections({
      knowledge: {
        pattern: 'knowledge/**/*.md',
        refer: false
      },
    …

In a template you can then iterate over the collection:

{{#each collections.knowledge}}
<li><a href="/{{../../site.locale}}/{{ path }}/">{{ title }}</a></li>
{{/each}}

We already do the same for blog posts, TSC minutes, etc.

[Qard]

Oh, cool. Good to know. Sorry, I'm a bit of a noob to metalsmith.

What about the tag grouping idea? Is there collection nesting? It'd be nice to have a more automated way to group and sort the knowledge base docs.

I'll take another pass at it in the morning. 😸

[fhemberger]

We created different sub-collections for the blog as well: https://github.com/nodejs/new.nodejs.org/blob/master/build.js#L68

I haven't checked all the new docs yet, so I can't tell you what grouping makes sense. Will try to have a first look later.

[Qard]

The knowledge base md files have both folder structure arrangements and tags. Both of which will probably change a bunch over time, so manually defining each collection like what has been done with the blog is somewhat un-ideal. I'll do some digging to see if there's a better way.

[mikeal]

+1 this is the existing structure from the nodejitsu docs. Even if we want to alter the structure it would be less work to shift a few things around and maintain the folder structure.

[Qard]

The "knowledge base" thing overlaps with the docs wg plan of having "guides" type docs. My thought was that those would probably get merged eventually.

[mikeal]

Ya, should probably merge the guides in at some point. Not sure if there are any format differences.

[Qard]

The docs wg has less stuff currently, so it might make the most sense to make it conform to the knowledge base format. I've opened some PRs to port the docs commits over here. The tracking issue for that is here: nodejs/docs#44

[Qard]

I tried the layout approach. Not too sure about the sidebar code duplication though.

[fhemberger]

Related to #211 (waiting for ok for copyright transfer), thus flagged as 'do not merge' for now.

[mikeal]

actually, we can merge this because it's against the knowledge-base branch and not master.

[Qard]

Yep, if you are satisfied with it, feel free to merge. Otherwise, let me know if you want any further changes. :)

[fhemberger]

Merged into knowledge-base branch