Specification template - 2nd iteration

[squidfunk]

The first iteration of the ToIP documentation and specification template is out of the door, so I want to explore some directions which would make the experience even better. As the general documentation template should work pretty well out-of-the-box, as it's close to Material for MkDocs common use case, I'll dive into the specification template.

ToIP specification template

A resilient and sustainable rebuild

Currently, the ToIP specification template is a modification of the ToIP documentation template. This means that essentially the CSS was monkey-patched, trying to bring the design and mechanics as close to SpecUp as possible, as specifications are not a primary use case of Material for MkDocs. A more sustainable and flexible approach would be to ...

• ... use the HTML and JavaScript of squidfunk/mkdocs-material as a basis, but strip out the entire CSS
• ... implement the CSS from the ground up to match the look of SpecUp

This means that CSS changes in the upstream Material for MkDocs will never impact CSS changes in SpecUp, which could easily be the case, as the CSS is overridden and not replaced. All functionality would be re-used from the base template, as the overall structure does not need to be changed.

Multi- and single-page specifications

The second thing that we could improve on is the fact that with MkDocs, documentation is inherently structured on multiple pages. The table of contents is only available for the current page, which is why the table of contents in the specification template will only expand for the current page.

Sidenote: what sounds like a limitation, can actually be a good idea for huge specifications. Taking the HTML 5 specification as an example, the HTML alone has a size of 11.9MB, leading to abysmal load times, even on broadband:

Material for MkDocs provides a pretty good client-side search, which helps to navigate among those multiple pages.

Nonetheless, it may be desirable to render specifications as single pages. As we did all the groundwork for concatenating multiple Markdown documents into a single document as part of the first iteration, we could leverage this concatenated Markdown file and render a single-page specification. This means, we could implement two flavours of the specification template:

1. Multi-page, expanding the table of contents for the current page
2. Single-page, only consisting of a single table of contents

Possible solutions can be a custom build process or encapsulating the page-merging and rendering logic as part of an MkDocs plugin, contributing back to the community. This is something, which we need to plan for when doing the rebuild of the specification template.