Implement a new HTML front end with Bulma

[mortenpi]

Demo:

• Documenter's manual: https://mortenpi.eu/gsoc2019-mockups/bulma/v13/documenter/
• The Julia manual: https://mortenpi.eu/gsoc2019-mockups/bulma/v13/julia/

TODO:

• Need to add the SCSS sources, requires basic APIs in DocumenterTools
• Handle tables overflowing
• Fix the search page
• Revise sidebar menu styling, layout (close Navigation sidebar not usable on iPad #638)
• Try out a few other fonts
• Footnote "back-references" (click on def, jump to location)
• Colophon (for now, it's implemented as a settings dialog; close “When was the documentation last updated?” #724)
• Flakiness when clicking on search results? (Seems fine now)
• It seems that sidebar vertical height can be buggy on mobile when the browser top bar disappears.
• Page Down does not scroll the main body by default (since the scrollbar is actually for an inner <div>; won't fix now, but might revisit the use of bulma-dashboard)
• Footer theming
• Fiddle with the color scheme (close Note section in new darkly theme #1085)
• Syntax highlighting in admonitions in the dark theme.
• Different logo for dark theme (Different logo for dark themes #1090)
• Fix note admonition styling (close Style info admonitions correctly #1030)
• Link to point to the GitHub repo root
• List margins

Close #626, close #722. Also addresses #981, #618.

[pfitzseb]

If you make it specific to levels > 1, then you can put something like

margin-left: -1em;
margin-right: 0;
background: $sidebar-background;

here to get what I showed on Slack.

[cormullion]

I love this, especially the Dark Mode, which is always interesting to design for. I wonder whether the Notes (if not the Warnings) could be dimmed a bit, so as not to be so distracting...?

Also, I think the Julia logo could be inverted?

Anyway, it looks great!

[Datseris]

Hello! Just came here to add exactly the same comment as @cormullion , but of course cormullion being cormullion did it much before me! I also thing the warning boxes should use a bit more saturated colors. It makes it easier on the eyes. Also, a light gray background over the text in the white version would help (as at the moment you cant really tell when the block ends)

[mortenpi]

Also, I think the Julia logo could be inverted?

Good idea, although I need to think about how to implement it (the logo and the theme are not technically related to each other). Do you have an SVG of the inverted logo by any chance though?

[pfitzseb]

Do you have an SVG of the inverted logo by any chance though?

See here or here.

[cormullion]

https://github.com/JuliaLang/julia-logo-graphics/tree/master/images

[mortenpi]

I left the colors slightly more saturated than what @cormullion suggested at the moment:

I feel that they are dimmed enough, yet nicely retain some colorfulness. Overall, I think I managed to take care of most color issues now (not the logo yet though). Feedback most welcome though. Here is the latest demo:

https://mortenpi.eu/gsoc2019-mockups/bulma/v10/documenter/showcase/
https://mortenpi.eu/gsoc2019-mockups/bulma/v10/julia/

[cormullion]

Lower contrast is great now.

(de gustibus non est disputandum) 😅

[cormullion]

On the Settings menu, is that "generated by Documenter... " the date of the document's generation (fixing #724 yay!), or something to do with the settings?

[mortenpi]

On the Settings menu, is that "generated by Documenter... " the date of the document's generation (fixing #724 yay!), or something to do with the settings?

That's when the document was generated (you can hover to see the time too). I put it into the settings dialog since I couldn't really figure out how to make it look readable and unobtrusive at the same time in the footer.

[cormullion]

Perhaps you could include the document name there, so that it's clear that it's this specific document, not the Documenter HTML theme, or whatever?

[mortenpi]

In case anyone is brave enough to review any of this, then now would be the time. I will appreciate any feedback 🙂 Generally, I think it's in good enough shape to be merged (we'll probably have some fixes in follow-up PRs), but I'll leave it open for a few more days.

[mortenpi]

Hmm, might be better to go back to Roboto Mono then, but have a slightly better fallback behavior than before:

font-family: 'Roboto Mono', 'SFMono-Regular', 'Menlo', 'Consolas', 'Liberation Mono', 'DejaVu Sans Mono', monospace;

Or, alternatively, we could try to target the OS default monospace fonts:

font-family: 'SFMono-Regular', 'Menlo', 'Consolas', 'Liberation Mono', 'DejaVu Sans Mono', monospace;

I don't really have a very strong opinion myself. The alignment problem of #618 is pretty much unsolvable, and not really a problem for the Julia manual anyway, so we can just focus on which one looks better.

[helgee]

Yup, those are correct. Although they don't come from Markdown -- they are just bullet points for the in-page headings, and intentionally look different from the rest of the sidebar in order to distinguish them from the inter-page links.

Maybe a different bullet, i.e. one that is not the same as Julia's comment character and Markdown headers, would be better? ;-)

BTW: This looks great 👍

[tkf]

It seems that syntax highlighting is broken:

from https://mortenpi.eu/gsoc2019-mockups/bulma/v7/documenter/man/syntax/#@ref-link-1

This happens if:

• You never visited the page (or cleared the cache?)
• And never switched to the dark theme.

Switching to the dark theme and then switching back to the default gives me:

[mortenpi]

@tkf Do you see the same issue with a newer version too?

https://mortenpi.eu/gsoc2019-mockups/bulma/v11/documenter/man/syntax/#@ref-link-1

[tkf]

Looks good to me. I didn't realize that the link in the OP was an older version.

[mortenpi]

Maybe a different bullet, i.e. one that is not the same as Julia's comment character and Markdown headers, would be better? ;-)

I personally actually like that it mirrors the Markdown syntax since you create those headings literally with a # (well, with ## normally).

Here are the latest builds (also updated the OP):

https://mortenpi.eu/gsoc2019-mockups/bulma/v13/documenter/
https://mortenpi.eu/gsoc2019-mockups/bulma/v13/julia/

[helgee]

I personally actually like that it mirrors the Markdown syntax since you create those headings literally with a # (well, with ## normally).

I see your point and I certainly could get used to it. It just sticks out a bit especially if juxtaposed with other bulleted lists (see below) and like @cormullion, I first interpreted it as a rendering error.

[ararslan]

I didn't even realize the hashes were intentional; I also thought they were an error.

[mortenpi]

I didn't even realize the hashes were intentional; I also thought they were an error.

Ok, three people reporting it means that it's no longer a matter of taste 😆 Swapped it out for circles:

[mortenpi]

I merged this so that any follow-up changes could be made in separate, more manageable PRs. This does not mean that any of the style etc. is final yet -- I opened a dedicated issue to collect feedback: #1091.