Abandon GitBook, look for alternatives

[PeterBowman]

We have a bunch of doc-only repos written in Markdown:

• https://github.com/roboticslab-uc3m/developer-manual
• https://github.com/roboticslab-uc3m/teo-developer-manual
• https://github.com/roboticslab-uc3m/installation-guides

This code is currently transformed into HTML by GitBook. At some point, $$$ took preference and a previously nice open source project turned to the darkprivate side of life, thus splitting paths: new development occurs now in a closed source "GitBook 2", whereas old projects (such as ours) can still pull from a FOSS "GitBook Legacy" fork: https://github.com/roboticslab-uc3m/questions-and-answers/issues/63.

Long story short, we were happily running a local installation of GitBook Legacy on our servers first, then on GitHub's servers via GH Pages and GH Actions (with some downsides): https://github.com/roboticslab-uc3m/questions-and-answers/issues/91#issuecomment-805120205. A couple of years ago, the intricacies of JavaScript package management by GitBook (feels like reinventing the Node.js wheel) proved this mechanism is badly broken:

• https://github.com/roboticslab-uc3m/docker-gitbook/issues/1
• https://github.com/roboticslab-uc3m/teo-developer-manual/issues/70

It is time to try something new! Requisites: must convert from Markdown to HTML, support plugins (i.e. for tables, SVG diagrams, TOCs), not require too much effort for installation and running from GH Actions/Pages (i.e. prefer apt to Docker images), be and stay free.

Important: make sure current links still work after the migration! (installation-guides is quite relevant on Google)

[jgvictores]

From https://github.com/myles/awesome-static-generators I'd look at:

• https://github.com/myles/awesome-static-generators#documentation
• https://github.com/myles/awesome-static-generators#wikis

Filtering, as you said, by:

• Markdown as a first-class citizen
• Support for plugins (pdfs and especially mermaid-js/mermaid (website))

[PeterBowman]

I decided to go on with MkDocs ("fast, simple and gorgeous"). It uses Python-Markdown under the hood. Alternatively, we could have used Sphinx with MyST:

• https://github.com/roboticslab-uc3m/teo-developer-manual/commit/2ece46b3152fc78c805f2d736708a28c04b21842
• https://robots.uc3m.es/teo-developer-manual/

References:

• https://www.mkdocs.org/user-guide/
• https://www.mkdocs.org/user-guide/configuration/
• https://squidfunk.github.io/mkdocs-material/
• https://squidfunk.github.io/mkdocs-material/setup/
• https://facelessuser.github.io/pymdown-extensions/
• https://realfavicongenerator.net/ (for generating the favicon.ico: favicon_package_v0.16.zip)

Quite happy with the result. Known caveats:

• No embedded PDFs on mobile view (example)
• navigation.instant has no effect on published GH Pages site, but does work locally

[PeterBowman]

navigation.instant has no effect on published GH Pages site, but does work locally

Sadly, I don't think instant loading will ever work on a static page server such as GH Pages. Without this, FOUCs may be pretty noticeable during navigation (I am still fiddling with this, but I have also found that choosing the right zoom level helps a lot). Per "Building for offline usage":

Limitations

Material for MkDocs offers many interactive features, some of which will not work from the file system due to the restrictions of modern browsers: all features that use the fetch API will error.

Thus, when building for offline usage, make sure to disable the following configuration settings: instant loading, site analytics, git repository, versioning and comment systems.

It does work when served via mkdocs serve, though. I am going to disable this feature and deploy via mkdocs gh-deploy:

• https://www.mkdocs.org/user-guide/deploying-your-docs/
• https://www.mkdocs.org/user-guide/cli/#mkdocs-gh-deploy
• https://squidfunk.github.io/mkdocs-material/publishing-your-site/

See https://github.com/roboticslab-uc3m/teo-developer-manual/commit/d3143b7456f36417c908ea596a82a5a521135f06.

[PeterBowman]

Our three formerly GitBook-enabled repositories have been migrated to using MkDocs:

• https://robots.uc3m.es/developer-manual/
• https://robots.uc3m.es/teo-developer-manual/
• https://robots.uc3m.es/installation-guides/

Important: Python-Markdown does not always match GitHub's Markdown implementation, therefore differences may arise between GitHub-rendered .md files and the published ones. I'd recommend editing the files locally and checking the generated result prior to pushing it to GitHub.

[PeterBowman]

Python-Markdown does not always match GitHub's Markdown implementation, therefore differences may arise between GitHub-rendered .md files and the published ones.

Examples:

• Use <https://google.com> instead of https://google.com
• Use four spaces for indentation of nested lists, e.g.:

  - Fancy list item.
    - Fancy sublist item.
  - Even fancier list item.

• Avoid blank lines within a list's body, e.g.:

  - Fancy list item.
  Fancy description.
  
  - Another fancy list item.

  instead of:

  - Fancy list item.
  
  Fancy description.
  
  - Another fancy list item.

• Add a blank line between a paragraph and a list that follows, e.g.:

  Fancy paragraph.
  
  - Fancy list item.

  instead of:

  Fancy paragraph.
  - Fancy list item.

cc @jgvictores