Closed PeterBowman closed 9 months ago
From https://github.com/myles/awesome-static-generators I'd look at:
Filtering, as you said, by:
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:
References:
Quite happy with the result. Known caveats:
navigation.instant
has no effect on published GH Pages site, but does work locally
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
:
Our three formerly GitBook-enabled repositories have been migrated to using MkDocs:
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.
Python-Markdown does not always match GitHub's Markdown implementation, therefore differences may arise between GitHub-rendered .md files and the published ones.
Examples:
<https://google.com>
instead of https://google.com
- 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
We have a bunch of doc-only repos written in Markdown:
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:
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)