Meta: improvements to the HTML output

[mortenpi]

Various issues and thoughts that should or could be addressed that are related to the HTML output. Some of these might deserve a separate issue to actually decide the details. We could also add additional things here as they come up, so this could serve as a meta-issue.

Content

• Local vs web builds. Local docs (e.g. as distributed by system package managers) and web sites (e.g. gh-pages) have different requirements, e.g. URL schemes, same-origin policy, bundled scripts and styles (local sites should probably work offline). Instead of trying to accommodate both in the same output, we could just have a Formats.LocalHTML to generate sites that are meant to be used locally.
• Clean URLs. That the page URLs are latest/page.html is a bit ugly and we should switch to something like latest/page instead. For static sites we can achieve that by having latest/page/index.html (like MkDocs does). This won't work that well for local build though, so we'd need to split them up and have a serve function available to locally view the docs. (Allow using pretty URLs #485)
• Optimize the search. A bit vague, but both performance and content presentation could be improved. Blink.jl could be an option to run some of the index generation part of the lunrjs while building the docs.
• Multi-version support. The Julia manual has a widget to switch between versions. I would propose a javascript-based solution, where we'd have a versions.{xml|json} in gh-pages top-level that gets updated on every deployment and contains a list of versions available. Then a small script would read that and display a small widget. Should be javascript based, so that you wouldn't have to update all the versions every time a new tag gets released etc. (Translated and Other Version Docs #297, Add version selector dropdown menu #358)
• Generator information. We could have have a small footer saying that it is generated by Documenter.jl, when and based on which commit. We should also populate <meta> tags with some of this information.
• Extra navigation links. The logo and title in the navigation menu should probably link to something (docs root perhaps? Logo currently points to the same page, which isn't that helpful). There should be a possibility of having an external link(s) as well (e.g. to GitHub or project website; I would have them separate from the logo/title though).
• GitHub stars. Like the MkDocs' Material theme.
• Smarter outline. Determining the document outline (which is used for the sidebar) should be more flexible (Blank title if anything before first header #256).
• Make the navigation menu more versatile. Have a mechanism to filter pages in the navigation menu (Build pages without adding them to sidebar? #230, Add an option to hide pages in sidebar #282).
• Additional formats for the logo. It currently assumes that the file is logo.png. We should probably also support additional extensions (.svg, .gif, .jpg, .jpeg, .webp). (Update HTMLWriter logo handling and arguments #953)

Style and layout

• Mobile UX. The style should have a responsive design. Currently mobiles also display the desktop layout (responsive side navigation #449).
• Next/prev page buttons. To have buttons (like the current Julia manual), instead of text links.
• Center the <article>. Like the current manual does. Should also probably snap left though, once the width gets large enough.
• Don't lower headers in docstrings. With HTML we could have normal header tags, and we'd just have to override the style. With HTML5 and since docstrings are wrapped in <section> tags, the semantic outline should also be correct.
• Allow blocks in Footnotes. Currently the HTML output assumes that footnote contents should all be inline, but it should actually support block level content as well. Ref: Update HTML docs #217.
• Style the quote block. The <blockquote> tag. Currently it is just indented. Probably just add gray background and border-left.
• Extend the navigation menu style all the way. If the page is longer than the navigation menu, the style cuts off. It should extend all the way down. (Fixed nav menu with scrolling overflow #321)
• Have the navigation menu scroll independently. E.g. GitBook or Material MkDocs theme. (Fixed nav menu with scrolling overflow #321)
• Collapse navigation sub-menus. Probably level 3 and deeper should not be displayed by default (Build pages without adding them to sidebar? #230; fixed by the hide feature in Add an option to hide pages in sidebar #282).
• Handle CDN failures better. If the CDN serving fonts or javascript libraries is not reachable, the page rendering blocks until the attempted connection times out (which can take up to a few minutes). This should be handled better, by either a graceful fallback or, alternatively, by bundling all the external dependencies into the HTML build.

HTML-enabled features

Some larger potential features that are possible thanks to our own HTML output.

• Separate reference manual. Have function, type, module etc. reference as a separate set of pages, one item per page. Every item would then have a systematic URL (e.g. /reference/Documents/Page) to page that would contain the docstring, but also additional information (source links, lists of methods etc).
• Source viewer. We could distribute the source files as a set of styled and highlighted pages along with the docs. This way there's no need to sync with GitHub etc. for source links and such, and we could even have search working over the source files. Currently the source links can be problematic since they depend on a particular commit etc.

[MichaelHatherly]

Good list, thanks for writing it up. I'm fine with all the items listed apart from the clean URLs one. I've never really understood why hiding the .html is worth the extra effort. Would be good to survey other doc generators and see what they all do.

Have function, type, module etc. reference as a separate set of pages, one item per page.

That's a lot of separate pages for Base, something like ~1900 of them. Not sure if that would be easier to navigate since some docs are just one-liners, meaning lots of clicking between pages when browsing. Worth looking into though, I'm not particularly against the idea at the moment.

[timholy]

Just about to kick the tires here. In contrast with what's stated here, there doesn't appear to be a test/html folder.

[MichaelHatherly]

In contrast with what's stated here, there doesn't appear to be a test/html folder.

@mortenpi is busy rewording some of that in #217 which removes the mention of test/html.

[mortenpi]

Added an entry to the OP.

• Extra navigation links. The logo and title in the navigation menu should probably link to something (docs root perhaps? Logo currently points to the same page, which isn't that helpful). There should be a possibility of having an external link(s) as well (e.g. to GitHub or project website; I would have them separate from the logo/title though).

[rsrock]

Nice list. By the way, have you seen this? It might make the whole job of setting up docs on GitHub even easier, if everything can stay on master.

[cormullion]

Just tried this out - it's fairly awesome! Congrats!

The first thing I noticed - the lines of the HTML are very long — typically up to 5000 characters or more. It doesn't cause any problems, but you could probably put returns after </p> and such like - it'd be easier to look at the HTML then.

[MichaelHatherly]

It might make the whole job of setting up docs on GitHub even easier, if everything can stay on master.

The trouble with using GitHub's new docs/ dir feature is that you'd have to commit Documenter-generated content to your master branch if I'm not mistaken. It's fine for projects with docs that are all just handwritten, but since we're mixing content from several different sources it won't quite work for us I don't think. If GitHub allowed you to run arbitrary code when building the site rather than just the basic Jekyll stuff, then that solution would be really nice and clean.

the lines of the HTML are very long

To look at the generated content I'd suggest just using the browser's "inspect" feature ("Inspect" in Chrome, and "Inspect Element" in Firefox) which formats the HTML nicely.

[davidanthoff]

I actually like clean URLs, so a +1 from me for that feature.

[davidanthoff]

This is a style suggestion: it would be great if inline text that is marked as a code block (i.e. uses double ` to start and end that block) would look similar to code that is marked that way for a whole paragraph. So, use a fixed-width font and have a gray background. Right now those inline code blocks are rendered as bold and italic and maybe a slightly larger font? That seems really not ideal, see e.g. the first paragraph here.

[davidanthoff]

On the extra navigation links: I think it would be really good if we could add a link back to the repo for the project somewhere. That seems to be one of the major navigations I use: go to the doc, browse around and then I want to go back to the project github page with one click. I could click back a lot, but would much prefer a direct link.

[mortenpi]

This is a style suggestion: it would be great if inline text that is marked as a code block (i.e. uses double ` to start and end that block) would look similar to code that is marked that way for a whole paragraph. So, use a fixed-width font and have a gray background. Right now those inline code blocks are rendered as bold and italic and maybe a slightly larger font? That seems really not ideal, see e.g. the first paragraph here.

Double backticks denote LaTeX in Julia's Markdown. Inline code should be surrounded by single backticks, and should be styled correctly. More accurately I think it was odd number of backticks for code, even number for equations/LaTeX.

[davidanthoff]

Double backticks denote LaTeX in Julia's Markdown. Inline code should be surrounded by single backticks, and should be styled correctly. More accurately I think it was odd number of backticks for code, even number for equations/LaTeX.

Ha, I didn't know about that, but this solves this completely, thanks!

[MichaelHatherly]

(FWIW there's a recent addition to the Julia docs that outlines all the markdown syntax that we currently support http://docs.julialang.org/en/latest/manual/documentation/#markdown-syntax.)

[tlnagy]

It would also be nice to add an option to include the number of stars on github under the logo like in the Mkdocs Material theme

[mortenpi]

Added to the OP:

• Handle CDN failures better. If the CDN serving fonts or javascript libraries is not reachable, the page rendering blocks until the attempted connection times out (which can take up to a few minutes). This should be handled better, by either a graceful fallback or, alternatively, by bundling all the external dependencies into the HTML build.

For background: yesterday morning (Oct 2) Font Library, where we get the Fantasque Sans Mono font from, went down for half a day, making all of the HTML builds unusable for that period.

[tlnagy]

Probably the most pressing feature on this list is a button to navigate to root page of the associated github repo. I currently always click "edit on github" and then navigate to the project root.

[KristofferC]

Looking at the screenshot below which is from chromium on linux:

In my opinion the distance between the bullets on the right is a bit large. Also, the style of the version selector feels a bit off (the current one gives me a Windows 98 vibe). It also feels a bit too close to the search box making it looked a bit cramped.

Just a few personal opinions :)

[MichaelHatherly]

The dropdown is should just be the default system one. Doesn't look a bit odd in chromium though. Tweaks to the css are most welcome, I'll get around to sorting them at some point, unless someone else beats me to it.

[omus]

Mobile UX seems important especially since the Julia manual has been ported to Documenter.

[KristofferC]

Another thing, when you click on a menu entry the menu get scrolled to the top. Is this a browser thing or is it possible to keep the position of the left menu and just refresh the right section. In documentations with a lot of menu entries (like the julia manual) it is a bit annoying to get taken to the top all the time.

[adigitoleo]

Next/prev page buttons. To have buttons (like the current Julia manual), instead of text links.

It would be nice if the buttons/links could have rel="next" and rel="prev" in the html. Some keyboard-controlled browsers have shortcuts for quickly following such links. In fact, the buttons in the Julia manual don't seem to have this either (not everywhere at least).

Then again, hardly anyone seems to use this anymore, apparently Google stopped using it for indexing at some point...