build VS mkdocs-material

If it's pure Python, the only packaging file you need is `pyproject.toml`. You can fill that file with packaging metadata per PEP 518 and PEP 621, including using modern build tooling like flit[1] for the build backend and build[2] for the frontend.

With that, you entire package build (for all distribution types) should be reducible to `python -m build`. Here's an example of a full project doing everything with just `pyproject.toml`[3] (FD: my project).

[1]: https://github.com/pypa/flit

[2]: https://github.com/pypa/build

[3]: https://github.com/pypa/pip-audit

RE the dislike of a "third-party tool", what do you mean by this? All the major tools for packaging in Python are under the PyPA, e.g. - twine - build - hatch

building wheels/sdists to upload or install: build

python3 setup.py sdist bdist_wheel - no need for an sdist when building wheels, also I'd recommend using pypa/build instead.

The first step is to turn the internal package into a wheel (a *.whl file). We can use the build tool for this purpose. After installing build with pip we can run it as follows:

Shouldn't https://github.com/pypa/build help? I don't think it has enough features yet but I was under the impression that was the distro solution.

8

Material Mk-Docs by Martin Donath works well if you prefer python.

https://squidfunk.github.io/mkdocs-material/

I'm an 'outsider', but from from the outside the Material For MkDocs Project looks like a very well managed open source project.

Martin Donath's project uses a 'sponsorware' release strategy to generate donations.

From my vantage point it seems to be working pretty well.

I just recently went through this decision process. My aim is to write code and math oriented posts so I need good support for nice syntax highlighting (at least colored) and mathjax (preferable) or katex. Substack is the most popular newsletter platform but fails at these two criteria. I love how math and syntax highlighting (plus numerous other features) work in MkDocs Material, which recently added a Blog plugin.

I wanted to combine the best of both: Substack as an amazing email social network, and MkDocs Material’s awesome look. So I’ve gone with using Substack as the core platform which I use to manage subscribers, and use it to post either math/code-free posts or a short teasers pointing to my main blog site on MkDocs Material when I need to show math/code

https://squidfunk.github.io/mkdocs-material/

I've been migrating content to MKDocs (Material) over the last few months, so feel fairly qualified on this subject. It's somewhat limited in terms of navigation, but can probably handle 400-500 pages; you can see how navigation works in the link. Otherwise, it can handle most, if not all, the tasks you've listed.