Doc: sync from Wiki, generate HTML

[virtualtam]

Closes #291
Fixes #227

Modifications

• HTML content: match the new Wiki structure
• Makefile
  • generate a custom HTML sidebar
  • include the sidebar on all pages
  • infer and prepend page titles
  • handle relative links
  • add title metadata, e.g. Shaarli - <Page Name>

[ArthurHoaro]

The new organisation is great.

"3rd party libraries" and "Community & Related software" cover almost the same subject.

Also, I see two things missing:

• Main title in sub-pages (e.g. "Troubleshooting" at the top of Troubleshooting.html).
  Pandoc variables could be enough.
• Link to go back to index.html (e.g. using pandoc -B and/or -A).

More.

[virtualtam]

"3rd party libraries" and "Community & Related software" cover almost the same subject.

May be confusing 'cause the first one is empty (for now):

• 3rd party => libs included in Shaarli (Awesomeplete, bLazy, CSS Reset, RainTPL)
• Community => derivative projects, forks, tools, alternatives

Main title in sub-pages
Link to go back

I've reworked the AWK hack for the index to be more concise & efficient, and am experimenting with solutions to improve navigability so it feels like being on GitHub :)

• navigation sidebar floating on the right
• page titles (head metadata, body header)

[virtualtam]

Makefile further tuned with MOAR AWK!

By the way @nodiscc @ArthurHoaro, is it really needed to keep the Markdown files under doc/?

[nodiscc]

@virtualtam awwwwesome work on the documentation! thanks!

About switching to multiple pages + sidebar: I somehow miss the possibility to search for a word (Ctrl+F) in a single page (for example I was searching for htaccess, which was moved to the Security page. I also agree that a single-page layout with a huge TOC is not very comfortable either. What do you think?

The last link "Usage examples" (possibly more?) in https://github.com/shaarli/Shaarli/blob/master/README.md#features is now broken (should be https://github.com/shaarli/Shaarli/wiki/Usage).

Maybe it's a good time to shorten the README? (update and group features, link to the main documentation on installing...)

[virtualtam]

Well, thanks :D

I went for a GitHub-like™ browsing Xperience for now, with the same multiple-page + sidebar look.

Another option would be to compile a proper one-file documentation for offline / dev usage, either as:

• a single HTML file containing
  • all GH pages, in [???] order (maybe parse the menu, and order content accordingly)
  • a custom sidebar (which wouldn't be very AWKward, from the current status)
• a single PDF file
• compiled HTML help (not sure this one is supported by Pandoc though)

It's mostly a matter of knowing which information and features are relevant for people using embedded documentation (like, you like Shaarli so much, like, you prepare your PRs, like, in the public transports, rofl)

Regarding a Search feature, I guess it could be easily done with a bit of JS.

And yes, the README may be a bit behind, but I'd prefer to wait for this PR's content to be discussed, reviewed and merged before updating it ;-)

[virtualtam]

Hello!

The relative links should now be OK, I've improved the AWK parsing to also process page content. The only case it won't work is when creating relative links with a custom name, e.g.
[I like trains](Railway Addiction).

Those are quite rare in the wiki, so this shouldn't harm browsing too much :)

#312 opened to add full-text search, suggestions of lightweight search libs are very welcome ;-)