Use index pages + automatic navigation arrows

[lierdakil]

This PR enables using _index.md pages for chapters and adds automatic generation of navigation arrows (#22). I tried hard to keep this backwards-compatible, and it seems to be, for the most part. A caveat is that automatic navigation errors arrows may not work for legacy structure (with index.md pages) 100% of the time (although a hack to make it work most of the time is included).

Changes:

• Chapter pages should now be named _index.md
• chapter: true is unnecessary for _index.md files
• New site parameter autoNav enables automatic navigation arrows. prev and next page metadata options are still supported as overrides. Setting prev: false or next: false disables an arrow on that page.
• menu site parameter is superseded by weight-based ordering of _index.md pages. Weight of _index.md pages works exactly like weight of normal pages, but on chapter level.

All of those changes are recommendatory, i.e. it should still work with old sites just fine.

[matcornic]

@lierdakil Thank you for your PR and first (big!) contribution 😃

Sorry, I did not see this PR before. I will look into it ASAP.

[lierdakil]

Gods above. I noticed a typo.

automatic navigation errors

This should be "navigation arrows". I have no idea how arrows became errors.... Probably mobile autocorrection.

[matcornic]

I got the following error by testing your PR with hugo-learn-doc:

Started building sites ...
ERROR 2017/03/25 18:08:04 theme/partials/menu.html template: theme/partials/menu.html:38:37: executing "theme/partials/menu.html" at <after 1 $value>: error calling after: no items l
eft

• tested with Hugo 0.19 and 0.20-Dev, not tested with previous versions
• tested without any change on the doc, just to see 'raw' compatibility

As an testing example, feel free to fork https://github.com/matcornic/hugo-learn-doc .
Be aware to go to http://localhost:1313/hugo-learn-doc/basics/ instead of http://localhost:1313/hugo-learn-doc/ otherwise you will be redirected to online website.

Please rebase before testing with Hugo 0.20, i just fixed another error (same as https://discuss.gohugo.io/t/v0-20-error-error-calling-isset-unsupported-type-invalid/5668).

Thanks again 👍

[lierdakil]

Okay, I believe this particular problem is fixed now. Apparently, after errors when it has to return empty array. I'd say it's rather unintuitive, but oh well.

[matcornic]

It seems to work great after my fix 👍

[matcornic]

I tested it again, and I have problems when using baseurl for arrow links. For example, I use "https://matcornic.github.io/hugo-learn-doc" as baseurl in my config.toml. So when I hugo serve, the server is starting at http://localhost:1313/hugo-learn-doc/

But, when I set autoNav=true, href of arrows links are not the right ones. For example:

• Current page: http://localhost:1313/hugo-learn-doc/basics/
• Arrow link expected: http://localhost:1313/hugo-learn-doc/basics/what-is-this-hugo-theme/
• Actual arrow link: http://localhost:1313/hugo-learn-doc//hugo-learn-doc/basics/what-is-this-hugo-theme/

It seems we have already the $.Site.BaseURL in .URL. I removed it locally and it seems to work (when I set baseurl or not)

prev/next parameters overriding have to keep $.Site.BaseURL though.

[lierdakil]

Okay, that's kinda obvious in hindsight. Fixed.

I also changed {{$.Site.BaseURL}}{{ . }} to simply {{ . | relURL }} in manual part, to make those closer in effect to automatic ones (since Page.URL is relative to site root, and doesn't include schema or hostname parts). As a side note, probably should also think about trimming down on direct BaseURL usage in other places (in particular, link and script tags).

[matcornic]

Got 2 more problems:

1. Menu sorting does work when mixing chapter and pages at the same level. For example, at level 0, we have chapter basics and cont and page contributing:

.
├── basics
│   ├── **_index.md**
│   ├── configuration
│   │   └── index.md
│   ├── installation
│   │   └── index.md
│   ├── requirements
│   │   ├── images
│   │   │   └── magic.gif
│   │   └── index.md
│   └── what-is-this-hugo-theme
│       ├── images
│       │   └── grav-overview.png
│       └── index.md
├── cont
│   ├── **_index.md**
│   ├── archetypes
│   │   └── index.md
│   ├── markdown
│   │   └── index.md
│   ├── pages
│   │   ├── images
│   │   │   ├── pages-chapter.png
│   │   │   └── pages-default.png
│   │   └── index.md
│   └── shortcodes
│       └── index.md
└── contributing
    └── **index.md**

2. The breadcrumb is wrong, content seems to be shifted bewteen pages

Moreover, could you change min_version to 0.19 in config.toml, you used functions not available in older version ?

[lierdakil]

Okay, so I never intended for mixing index.md and _index.md, and index.md is a dirty hack anyways (which may or may not work depending on environment, see e.g. gohugoio/hugo#2802). AFAIK Hugo uses two-tier model, so contributing is a category regardless of how you slice it =\

I've added a few workarounds, which should help, but the gist of it is that index.md should be avoided at all costs, since it usually creates a race condition (due to a name clash)

So yeah, I didn't think about wanting a non-chapter on the top level. So I changed how chapter metadata parameter is treated: it's now an override, i.e. if you specify chapter: false in metadata, page will be rendered as regular page regardless of if it's _index.md or not. So that should work, right?

└── contributing
    └── _index.md

in _index.md:

chapter: false

Breadcrumbs were an honest oversight, I just didn't notice until now. That should be fixed.