Hi folks,
There’s a new experimental website build for Beman hosted here under Home | The Beman Project . The intention of this redesign was to natively support API documentation and hosting the markdown documentation files from various beman projects on the main beman website under the “Docs” tab. The source code is hosted on the bemanproject GitHub and is a fork of the current website repository.
The website is built as a mix of:
- mkDocs as a replacement of docusaurus. mkDocs is faster and has a cleaner sidebar feel which integrated well.
- Antora + Pandoc to parse markdowns and build the Docs page.
- MrDocs to automatically build documentation for beman projects (with room for customization per repository).
Included libraries and markdown files are listed here in the website repository.
I’ve tried to test all pages on desktop and mobile and they feel nice and smooth. Pages worth trying to see all parts of it:
Some interesting notes from this:
- Antora and mkDocs generate the exact same pixel-perfect topbar / layout, while being two separate engines. One for the blog etc, and one for the docs etc. User should not realize.
- Antora / pandoc’s markdown parsing needed a slight preprocess to recognize some specific HTML that people often add to their github-style markdown files in their libraries.
- Dark mode is pretty much added as a css theme since it wasn’t supported in these generators but it looks pretty good to me.
I’m looking for thoughts from the community, so we can decide if this is missing any critical features, so we can move towards a consensus on this.