Add zensical as an alternative docs build path#199
Merged
Conversation
added 2 commits
May 1, 2026 17:48
- New zensical.toml ports the mkdocs.yml setup (theme, nav, mkdocstrings, markdown extensions) so `zensical build` renders the existing mkdocs/ source without touching content. - New scripts/post_zensical.py copies .md sources into site/ (rendering reference pages from HTML) and patches gallery MD links that zensical's link rewriter collapses into the API URL. - New mkdocs/demos.md plus a Demos nav entry, with .youtube-embed CSS for responsive 16:9 iframes. - New .github/workflows/docs.yml deploys via the GitHub Pages artifact flow. - Makefile gains `docs-zensical` and `docs-zensical-serve` targets; the existing mkdocs targets are unchanged.
- Delete mkdocs.yml and scripts/copy_docs_md.py. - Drop mkdocs / mkdocs-material / mkdocs-jupyter / mkdocs-section-index / mkdocs-include-markdown-plugin / mkdocs-git-revision-date-localized-plugin / mike from the docs extras; mkdocstrings[python] stays for zensical's compat layer. - Inline the HTML→markdown helpers from copy_docs_md.py into post_zensical.py so it's self-contained. - Replace the mkdocs Makefile targets with `docs` / `docs-serve` calling the zensical pipeline.
3 tasks
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.
Summary
zensical.tomlthat mirrorsmkdocs.yml(theme, nav, mkdocstrings, markdown extensions) sozensical buildrenders the existingmkdocs/source without touching content.scripts/post_zensical.pycopies markdown sources intosite/(rendering reference pages from the built HTML) and patches gallery MD links that zensical's link rewriter collapses into the API URL.mkdocs/demos.md) with three YouTube embeds, plus.youtube-embedCSS for responsive 16:9 iframes..github/workflows/docs.yml, and addsmake docs-zensical/docs-zensical-serveMakefile targets; the existing mkdocs targets are unchanged.Test plan
make docs-zensicalbuilds with no warnings (currently ~1.5s).make docs-zensical-serveand visithttp://localhost:8000/: gallery renders, "API" link goes to the rendered page, "MD" link serves raw markdown,/demos/shows three embedded videos,/llms.txtis reachable.make docs(mkdocs side-by-side) still builds.actions/deploy-pages, not the legacygh-pagesbranch.