It's difficult to navigate through the different Github Pages documentation pages

Since moving the documentation to ASCIIDoc, it’s become more difficult to navigate between the various pages.

The index.adoc links to the disruptor.adoc (Technical Paper), changelog.adoc (Changelog) and user-guide/index.adoc (User Guide), but none of these pages have links to the other pages or back to the main page.

There are a couple of ways to address this - the easiest being to stick links between the pages at the top of every document. It’s a bit of a rough solution, but it should make things a little better until a better structure for the pages is ready.

[swarren12]

It’s definitely better, having links there is a good thing. Is there no way to make it a global include rather than having to put it in every file? One forgotten include and suddenly there’s an orphaned page.

There are a few alternatives that don’t require it to be included, I’m just trying to work out which one is the nicest.

Side-note, having the changelog in there and a project-level markdown file is some less desirable duplication. Didn’t even notice it was in added to the doc source since previously there wasn’t an obvious link to it.

Yeah… I don’t think I realised there was a Markdown version until the other day. We could probably remove one of them and I have no issue with it being the .adoc.

I am still not 100% sold on asciidoc being better than using jekyll. The effort spent on adciidoc so far does feel like it could have been better spent improving the content of the documentation rather than the build pipeline for it and attempting to fit a square menu-like peg into a round asciidoc shaped hole? Maybe we need to start flexing some of the benefits that asciidoc has?

I feel this is very much an “eat the frog”. I’ve started looking at improving the content of the docs, but it’s a fairly big job and so it’s nice to hack off some other low-hanging bits of fruit on the way. I’ll see if I can raise another PR in a day or two that makes a start on addressing this (and will start making use of some ASCIIDoc features!)

[Palmr]

@Palmr Have you actually managed to get Jekyll to work on GitHub pages though? In my experience it was a complete nightmare.

Yes, this was the previous setup we had for github-pages before it got asciidoctored.