Sphinx [1] gets my vote. It's the docs system that powers most sites in the Python ecosystem so it probably looks familiar to you.
I call it a docs system rather than static site generator because the web is just one of many output targets it supports.
To tap into its full power you need to author in a markup that predates Markdown called reStructuredText (reST). It's very similar to Markdown (MD) so it's never bothered me, but I know some people get very annoyed at the "uncanny valley" between reST and MD. reST has some very powerful yet simple features; it perplexes me that these aren't adopted in other docs systems. For example, to cross-link you just do :ref:`target` where `target` is an ID for a section. At "compile-time" the ref is replaced with the section title text. If you remove that ID then the build fails. Always accurate internal links, in other words.
The extension system really works and there is quite a large ecosystem of extensions on PyPI for common tasks, such as generating a sitemap.
The documentation for Sphinx is ironically not great; not terrible but not great either. I eventually accomplish whatever I need to do but the sub-optimal docs make the research take a bit longer than it probably has to.
I have been a technical writer for 11 years and have used many SSGs over the years. There's no perfect SSG but Sphinx strikes the best balance between the common tradeoffs.
I can't recommend this enough! It's such a quality of life improvement to get the powerful dynamic documentation features of rST and Sphinx (and its many extensions), but in the more pleasant and familiar syntax of Markdown. I use MyST + Sphinx for all my project docs now.
A Sphinx plugin[0] allows for writing in markdown, and I'd heavily encourage using it if you're looking to get widespread adoption of sphinx on a project or at a workplace. Rst is fine once you learn it but removing barriers to entry is useful.
edit: my understanding of feature parity in reST/Markdown seems outdated - comment below might be incorrect
The value prop of Sphinx goes down a lot if you're not using reST because you can't use the extensive catalog of directives, such as the ref directive that I mentioned in my first comment. If you must use Markdown then there's not much difference between Sphinx and all the other Markdown-powered SSGs out there. In other words there's not a compelling reason to use Sphinx if you've got to use Markdown.
From Sphinx's Getting Started page:
> Much of Sphinx’s power comes from the richness of its default plain-text markup format, reStructuredText, along with its significant extensibility capabilities.
It works with all docutils and Sphinx roles, and almost all directives, including extensions.
A notable exception is autodoc (automodule, autoclass, etc.), and any other directives that generate more rST. The current workaround is to use eval-rst:
I have always found sphinx challenging, in usability or syntax :(
It could be probably much more advanced, but I went for pdoc3 for api docs and mdbook for documentation in general.
What I really hope that exists, is a system where I can reuse the documentation (sections) in other pages, ergonomically
I built that system multiple times to do preprocessing with things like including parts or special linking or referencing images from anyhwere
irobinovitch just corrected me that the library that provides Markdown support for Sphinx supports the features [1] that I care about; have to dig into the details but if the feature parity is very good and you strongly prefer Markdown over reST then I would say... go for the Markdown!
Just want to +1 this, and also add a twist. The Sphinx community also has a great extension called hieroglyph, which lets you use rST directives to build slide presentations which also double as single-page HTML notes documents.
This meant I could first write a blog post on learning Clojure as a Pythonista[1]; then turn some code samples and tables and images into slides I could present at a public talk on my laptop or desktop[2]; and then finally publish a public notes document that talk attendees could use to easily study or copy-paste code examples[3]. (The notes are the exact same contents of the slides, just rendered in a simple single-page HTML format, with each slide transformed into a section heading, with permalinks/ToC auto-generated.) So, this is generated HTML from a single .rst source[4], all the way down! And, of course, I could version control and render the .rst file powering the slides / notes / etc. in GitHub.
Note: the slides in [2] do not play well on mobile. You are meant to use keyboard arrows to advance and tap “t” to switch into tiled mode (aka slide sorter) and “c” to open a presenter console. The slides are powered by a fork of html5slides, which will look familiar if you’ve seen the JS/CSS slide template that Go core developers use in https://go.dev/talks (they generate those with “go present,” a different tool, though).
More recently, I have also used a similar-in-spirit tool called marp (https://marp.app) for generating technical slides from source, but the output and functionality was never quite as good as rST + Sphinx + hieroglyph. The big advantages to marp: Markdown is used as the source, some tooling allows for VSCode preview, and PDF export is fully supported alongside HTML slides.
I have a soft spot for Sphinx, not only because it was responsible for so much great documentation of Python open source libraries (including Python’s own standard library docs at python.org), but also because the first comprehensive technical docs I ever wrote for a successful commercial product were written in Sphinx/rST. And the Sphinx-powered docs stayed that way for a ridiculously long time before being moved to a CMS.
I call it a docs system rather than static site generator because the web is just one of many output targets it supports.
To tap into its full power you need to author in a markup that predates Markdown called reStructuredText (reST). It's very similar to Markdown (MD) so it's never bothered me, but I know some people get very annoyed at the "uncanny valley" between reST and MD. reST has some very powerful yet simple features; it perplexes me that these aren't adopted in other docs systems. For example, to cross-link you just do :ref:`target` where `target` is an ID for a section. At "compile-time" the ref is replaced with the section title text. If you remove that ID then the build fails. Always accurate internal links, in other words.
The extension system really works and there is quite a large ecosystem of extensions on PyPI for common tasks, such as generating a sitemap.
The documentation for Sphinx is ironically not great; not terrible but not great either. I eventually accomplish whatever I need to do but the sub-optimal docs make the research take a bit longer than it probably has to.
I have been a technical writer for 11 years and have used many SSGs over the years. There's no perfect SSG but Sphinx strikes the best balance between the common tradeoffs.
[1] https://www.sphinx-doc.org/en/master/index.html