Support for breadcrumbs

[joostdecock]

This PR adds support for breadcrumbs. Specifically, it adds a breadcrumbs config option (false by default) that will generate breadcrumbs to map the path between the top level of your content directory to the current file.

Example: Given this config:

['en/docs', {
      page: '/docs/_page',
      permalink: '/docs/:section*/:slug',
      isPost: false,
      anchorLevel: 4,
      breadcrumbs: true
}],

and a content structure like this:

• en/docs
  • about.md
  • help.md (1)
  • help
    • index.md (2)
    • faq.md

(1) (2) : One of my pending pull requests (link) adds support to make (2) replace (1)

The following will happen:

• about.md and help.md (1) or index.md (2) will not get any breadcrumbs added to it. That's because there are no intermediate steps between the root level and the page
• faq.md will get an extra property in its attributes called breadcrumbs. It will hold an array with for every step along the way (only one in this case) an object as such:

{
  frontMatter: { /* object holdiing the frontmatter for this breadcrumb */ },
  permalink: "/permalink/of/this/breadcrumb"
}

Here's an example of what the content-api returns for a real (and deep) page:

{
  "title": "Deep page",
  "hi": "mom",
  "contentLocale": "en",
  "breadcrumbs": [
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really"
    },
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really/deep"
    },
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really/deep/path"
    },
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really/deep/path/with"
    },
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really/deep/path/with/loads"
    },
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really/deep/path/with/loads/of"
    },
    {
      "frontMatter": {
        "title": "Index placeholder",
        "contentLocale": "en"
      },
      "permalink": "/docs/really/deep/path/with/loads/of/slashes"
    }
  ],
  "meta": {
    "index": 0,
    "fileName": "page.md",
    "section": "/really/deep/path/with/loads/of/slashes",
    "dirName": "/en/docs"
  },
  "date": "2018-03-27",
  "path": "/docs/docs/really/deep/path/with/loads/of/slashes/page",
  "permalink": "/docs/really/deep/path/with/loads/of/slashes/page",
  "anchors": [],
  "body": "<p>This is something ay?</p>\n"
}

This PR is most useful to people with a nested directory structure in their content directory. Adding breadcrumbs to your page layout is trivial this way.

Note: For this to work, you must have directory indexes for all the directories in your content directory. But if you're not doing that, then you risk 404 when a user manually goes up one leven in the URL anyway

[andrevandal]

It's good enough for me. Thanks for explanation! Could you add this into the documentation?

[joostdecock]

Yeah, if it gets merged, I plan to write up a section on all of this new stuff.

Longer term, I'd like to understand how the deployment of new versions and the docs site is organised. This is arguably the perfect module to have a kickin' documentation site ;)

[joostdecock]

I'm merging this into a (newly created) dev branch as a sort of go-between solution as I'd like to consolidate these PRs, but feel it's perhaps best to not merge them into master without review by @apmontgomery