Skip to content

Improve AsciiDoc-generated documentation HTML style

We now generate multi-page HTML from HTML files generated by AsciiDoctor (#36 (closed)). We want to improve the HTML style of the generated HTML pages:

  • Custom stylesheet:
    • Make a custom AsciiDoctor stylesheet, based on the default AsciiDoctor stylesheet. (!750 (merged))
    • Style it more like the ESCET website:
      • Switch to sans serif font. (!750 (merged))
      • Ensure the chosen font makes it easy to distinguish l/1, 0/O, etc.
    • Give the different docsets a color scheme more similar to their corresponding website. (!750 (merged))
    • Fix styling issues:
    • Styling improvements:
      • No section anchor links in HTML output, even though enabled. (was solved a while ago)
      • Reduce the large vertical spacing between lines, especially for code blocks. (doesn't seem present anymore)
      • Use slightly darker code block background to make it pop out a bit more. (doesn't seem needed anymore)
      • Link style in general could be improved. (no idea anymore what was meant here)
      • Justify text. (tried it, but it looks ugly)
      • Improve table style. (no idea anymore what was meant here)
      • Hover over code block shows e.g. 'CHI' in capitals. (!750 (merged))
      • Let browser decide column widths. Use \[%autowidth.stretch\] or \[%autowidth\] for tables (not recognized by docbook converter used for PDF generation). Or, just override the column width with CSS to be automatic.
      • Distinguish internal vs external links. (!750 (merged))
      • Don't wrap code blocks, but show a scrollbar instead. Do still wrap inline literal text. (!750 (merged))
      • Improve menu and btn macro styles. (!750 (merged))
  • TOC structure/styling improvements:
    • Put a symbol before each TOC item. The current indentation doesn't make it very clear what are different pages, especially with longer and wrapping section names. (!750 (merged))
    • Make TOC interactive with collapse/expand (fold/unfold) interactivity. The current TOC of the CIF documentation is very long, so navigating is becomes cumbersome and users use page search to find things. Going to another page you lose where you are. It is then cumbersome to go to a sibling page, for instance. (!750 (merged))
    • Fix TOC highlighting and expanding for current section on a page (rather than the entire page). (!759 (merged))
    • Fix TOC links for virtual sections (non-page, non-section ones). They are wrappers only in the TOC. Not actual sections on the pages themselves. Typically they are italic/bold texts, with or without an id to link to. (!761 (merged))
    • Ensure that virtual TOC entries are taken into account for breadcrumbs. (!763 (merged))
    • Animate TOC collapse/expand. (!767 (merged))
    • Generated JS code needs a license header. (!794 (merged))
  • Syntax highlighting: (#740 (closed))
    • Enable syntax highlighting, for built-in languages. (was solved a while ago)
    • Enable syntax highlighting, for Eclipse ESCET languages, so syntax coloring for Chi, CIF, SeText, ToolDef, console, SVG, BNF, etc.
  • PDF styling:
    • Reconsider whether we want to keep the PDF output at all. Does anybody use it? It takes a long time to render during builds.
    • Enable PDF section numbers for all sections, even though not in the TOC (for all levels).
    • Let PDF renderer decide table column widths by itself.
    • Use recommended syntax highlighter, Rouge. See also #740 (closed).
  • Code improvements:
    • AsciiDocHtmlModifier has two times Renamed that should be Rename in comments. (!768 (merged))

Old ideas

  • Bootstrap theme

    • Old text:

      The idea would be to base the documentation on Bootstrap if possible, to match the static website pages. It is also generally nicer and more modern. We could look whether there are any AsciiDoc Bootstrap-based themes/styles.

      The approach could be to:

      • First switch to a new theme/style.
      • And then fine-tune that global style to our own liking. These can happen incrementally, with one or a few changes per branch. E.g., adding syntax highlighting can be separate from table styles, for instance.

      This would be in line with #373 (comment 828292).

    • Rejected:

      I investigated this, but the AsciiDoctor skins that are based on Bootstrap don't have a TOC, etc. I think it is better to stay close to the default theme, but customize that to be more like the ESCET website. I've experimented with this over the past days, and it works quite well.

  • Inspiration other websites
  • Official Eclipse fonts
  • Deeper nested headings

    • Old text:

      Currently no styling for 'h7' to 'h9' tags (we have no h10). Only 'h1' through 'h6' are official HTML and have styling. Not needed if we do multi-HTML output first.

    • Rejected:

      AsciiDoc and HTML don't support 'h7' and further'. Also, we don't need it anymore, as we have multi-page HTML now.

  • Old TOC ideas

    • Old text:

      Bootstrap seems to support folding nav sidebars, see e.g. https://getbootstrap.com/docs/5.1/components/navs-tabs/. Not sure whether this requires completely generating different HTML from the AsciiDoc sources or not.

      Ensure that for longer TOCs and with multi-html page output (see #36 (closed)) the TOC scrolls to the currently visible HTML page. And maybe even to the correct section.

    • Rejected:

      The idea is not to use Bootstrap anymore. Scrolling is not necessary if the TOC is by default collapsed except for the 'trail' to the currently shown page. Then the TOC is so short that it fits on most screens most of the time, as there are not many root items, and the expanded items are not that numerous.

Edited by Dennis Hendriks

Copyright © Eclipse Foundation, Inc. All Rights Reserved.     Privacy Policy | Terms of Use | Copyright Agent