Implement MrDocs + Antora + mkDocs based documentation integration and website reimplementation - #197
Open
sakshamsharma wants to merge 18 commits into
Open
sakshamsharma wants to merge 18 commits into
sakshamsharma wants to merge 18 commits into
Conversation
This also moves to a new form of automation where github actions push to the gh-pages branch on a schedule and when triggered manually. This is a more robust solution than the previous cron job that pushed to the main branch, thus adding noise to it as well.
Use session storage instead of local storage to make it feel intuitive to the user if they refresh the page or reopen it.
Many markdown files (like docs/overview.md in Beman.eecution) contain HTML like <detail> <ul> <li> etc. Github renders this just fine. Pandoc does not treat markdown => AsciiDoc as an HTML compatible transformation and thus just drops those tags. This commit adds a preprocessing pass to our pandoc conversion which allows this content to remain as it was. TLDR; we convert GitHub-only HTML details into Antora-native collapsibles before Pandoc can destroy them. If the parser can’t find a balanced, valid-ish <details>...</details> block, it leaves that part of the Markdown alone and lets Pandoc handle it as before.
Also move out some generated python to a separate python script.
sakshamsharma
requested review from
JeffGarland,
RaduNichita,
camio,
ednolan,
inbal2l,
mguludag and
neatudarius
as code owners
September 17, 2026 23:22
❌ Deploy Preview for bemanproject failed.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR bundles together a big rewrite of the website's static generation scripts.
This is hosted here: https://bemanproject.github.io/website-experimental/
The discourse post describing this is here: https://discourse.bemanproject.org/t/new-v2-beman-website-with-docs/596
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 website is built as a mix of: