WIP: Feature/zensical - #259
Draft
rpietzsch wants to merge 56 commits into
Draft
Conversation
add package lifecycle
# Conflicts: # Taskfile.yml
re-enable `watch` as reload loop was fixed in that version.
add script building explicit `nav.yml` from `.pages` files wire `nav.yml` into config (`INHERIT`)
# Conflicts: # docs/automate/cmemc-command-line-interface/command-reference/package/index.md # docs/develop/.pages # poetry.lock
Dependencies - drop the private mkdocs-material-insiders fork for public mkdocs-material 9.7.x; removes the ACCESS_TOKEN secret and SSH key from CI and gitpod - drop Pillow and CairoSVG (social-card only) and the cairo apt step - pin zensical 0.0.57 with a note that the caret pin is deliberately narrow Features zensical does not implement, now handled here - self-host Roboto and Roboto Mono; theme.font: false stops the requests to fonts.googleapis.com and fonts.gstatic.com on every page - vendor tablesort, and glightbox, which zensical lazy-loads from unpkg at runtime on the image pages; tools/localize_bundle_assets.py rewrites the URLs baked into its JS bundle and fails on any new third-party host - replace mkdocs-redirects with static stubs for /cmemc/ and /explore-and-author/building-a-customized-user-interface/ - replace the meta plugin: comments default on, three pages opt out - drop the autolinks, privacy, meta and redirects plugin entries; keep social, tags and git-revision-date-localized so they resume when zensical maps them Rendering and navigation - drop the `extra` markdown extension: it bundles fenced_code, which competes with pymdownx.superfences for the ``` syntax. The winner depends on hash ordering, so roughly two thirds of builds mis-parsed `title="..."` fences and swallowed the following headings as raw text. Its other members are listed individually. See zensical/zensical#641. - build_nav.py: resolve a directory to its index.md and discover directories without a .pages file. Bare directory targets were never resolved to a page, costing those entries their icon and leaving the pages with no active nav position, which rendered the whole sidebar empty under navigation.tabs. It also restores 34 pages that were reachable on main but had no nav entry here. - override partials/tabs-item.html: zensical's version renders no icon, so the section icons never reached the tab bar - restore the Load Balancer tag icon with a neutral glyph; the Simple Icons AWS mark was removed upstream Guard rails - tools/check_zensical_output.py fails the build on a regression in anything we reimplemented, and reports social cards, tag listings and revision dates as PEND until zensical ships them - task check:nav fails if nav.yml drifts from the .pages files; also a pre-commit hook - both wired into task check and the CI workflows Social cards, tag listings and revision dates remain missing; see README.md.
…extra`: markdown.extensions.extra bundles fenced_code, which superfences is documented to replace. Enabling both is unsupported and left their precedence to hash ordering, so builds randomly mis-parsed `title="..."` fences and swallowed the following headings as raw text. Adds betterem, which fixes inverted emphasis on 4 pages. See zensical/zensical#882.
# Conflicts: # Taskfile.yml # poetry.lock
use native tag renderer (removed custom temp solution)
patch di reference template to render empty tag lists ("[]") instead of null ("")
The task regenerates nav.yml from the docs/**/.pages files, which puts it in the same family as update:cmemc, update:icons and the other regeneration tasks. Rename it accordingly and move it next to them, and update the two places that referenced the old name: the hint printed by check:nav and the navigation section of the README. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
Three scripts were still invoked as `poetry run python tools/<script>.py` while the other three had long been click commands on the dec-tool group. Wire the remaining ones up the same way, following the conventions the existing commands already established: named options with repo-relative defaults and show_default, the command writing its own output, and progress on stdout via click.echo. build-navigation --docs-dir docs, -o nav.yml, --check check-zensical-output --site-dir site localize-bundle-assets --site-dir site build_nav.py becomes build_navigation.py so that file and command agree, as they do for the other five. The __main__ blocks are gone: dec-tool is now the only entry point. --check is new. It compares the generated navigation against whatever -o points at instead of writing it, prints a unified diff and exits 1 on drift, which replaces the mktemp/trap/diff shell block in check:nav - renamed to check:navigation to match update:navigation. The pre-commit nav-drift hook follows both the task rename and the module rename. Verified with `task check` (all four stages, including a full build) and `pytest -m "not integration"`; `task update:navigation` regenerates nav.yml byte-identically. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
Bumping to Zensical 0.0.58 removed tools/render_tag_listings.py, the overrides/partials/tags.html partial and their tests, but left the README describing both as features "reimplemented here" - it pointed at two files that no longer exist. Tag listings and tag chip links are native now, so say that instead, and keep the paragraph on what check-zensical-output still guards: chips must link somewhere, and their anchors must exist on /tags/. The failure text of that very check named the deleted partial, which is the worst possible moment to read a stale hint. It now asks about Zensical. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
The builder had two tests, both on the click layer, while the logic that actually derives the navigation was unpinned. That logic carries the subtle rules: dir_title capitalises only all-lowercase names, which is what keeps "link-IDS-event-to-KG" from becoming "Link Ids Event To Kg", and expand_dir walks a directory that has no .pages instead of emitting a bare reference - a fix whose 12-line comment explains that bare references empty the sidebar under navigation.tabs and drop pages from the navigation entirely. Adds coverage for dir_title, read_pages, has_markdown, discover_dir's MkDocs-like ordering, expand_dir, expand_item, build_nav_list and render_nav's two error paths, plus the CLI cases that were missing: --check against a not-yet-existing file, and a --docs-dir that is not there. Checked that the tests can fail: making dir_title capitalise unconditionally breaks the acronym case, and reverting expand_dir to a bare directory reference breaks five. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D6WBueY2LvLdFZeNv2upnH
Expose every tools script as a dec-tool subcommand
Test Results1 files 1 suites 0s ⏱️ For more details on these failures, see this check. Results for commit 0329bff. ♻️ This comment has been updated with latest results. |
Restores the old sidebar behavior (e.g. release notes showing the current version as its own entry) lost when nav.yml generation collapsed single-index-page directories into flat links.
Enables navigation.path and overrides path.html to skip the leading homepage entry.
mike deploy builds and commits in one process, with no hook in between, so its bare `zensical build` would publish the unpkg.com URLs localize-bundle-assets removes. Build here instead; mike still owns versions.json, aliases, redirect.
Zensical publishing: mike fork, publish task, preview
nav.yml is generated by tools/build_navigation.py, and its output satisfied none of yamllint's default rules: no document start, and block sequences emitted at the same column as their parent key rather than indented under it. That is 280 indentation findings plus a missing `---` on a file nothing hand edits. Emit a `---`, and dump through a Dumper subclass whose increase_indent forces `indentless=False` so sequences nest beneath their key, as `indent-sequences` expects. The indent stays at two. Four is unreachable: `indentation` defaults to `spaces: consistent`, so every step in the file must be the same width, and a `- ` item prefix already costs two columns for the mapping key inside a sequence item. PyYAML's `indent=4` pads the dash to `- key:` and trips `hyphens`; re-indenting by hand to ` - key:` trips `indentation` instead. Both are recorded in a comment next to the dump so this does not get reopened. A handful of entries pair a long title with a long docs-relative path and exceed 120 columns. YAML folds plain scalars only at internal spaces, never after the `: `, so they cannot be wrapped - the generated header carries a `yamllint disable rule:line-length` directive rather than relaxing the rule for the whole repository. The regenerated nav.yml parses equal to its predecessor; the diff is entirely whitespace and the navigation is unchanged.
Preparation for the yamllint check added next: these are every finding it reports, fixed so the check can be turned on green. The .pages navigation sources make up the bulk. 64 gain a `---` document start and 30 a missing newline at end of file. One, deploy-and-configure/configuration/explore/dataplatform/.pages, is the only nested one and the only real error: its sub-list sat at column 8 where `spaces: consistent` wants 10, since the key it hangs off is at column 6 and the file's step is 4. Verified afterwards that the generated nav.yml is byte-identical, so none of this moves a page in the navigation. The three Helm values files under docs/ are downloadable examples rather than snippet-included, so nothing on a rendered page changes. They pick up an off-by-one nested indent, a doubled space after `secretName:`, bracket spacing, a missing final newline, a document start, and a comment reflowed under 120 columns. .github/ISSUE_TEMPLATE/bug.yml keeps its over-long line: the URL alone exceeds the limit and a folded scalar cannot help, because a line break inside one becomes a space and would break the Markdown link. It gets a `yamllint disable-line` directive instead, and the file still parses identically. mkdocs.yml and .gitpod.yml pick up comment spacing and a document start.
Nothing in this repository ran yamllint, so YAML style was unenforced and drifted - the previous two commits are the backlog that had accumulated. The config is committed rather than left to a user-level one. CI runs `task check`, and a GitHub runner has no ~/.config/yamllint/config, so without a repository config the stage would silently fall back to yamllint's stricter upstream defaults - line-length 80 above all - and fail on nearly every file while passing locally. .yamllint therefore restates the settings it is meant to mirror, and says so in a comment. `yaml-files` has to name `.pages` explicitly. yamllint selects by filename and its built-in globs only cover *.yaml, *.yml and .yamllint, so the 65 extensionless navigation sources - the files nav.yml is generated from - would otherwise go unchecked while the generated output was held to the rules. truthy is relaxed for keys so that `on:` in a GitHub workflow stops being read as the boolean. Wired into `task check` between check:rumdl and check:navigation, and into pre-commit with a filter that also fires on .pages. yamllint joins the dev dependency group; the lock file is refreshed because CI installs from it.
Make the generated navigation and the repository's YAML yamllint-clean
…ensical-breadcrumbs
With navigation.indexes every <dir>/index.md attaches to the section named after it, so the trail ended in a link back to the page you are on - already said by the sidebar and the title. Sections whose index is a different page keep their crumb. The tags leave content.html for the breadcrumb row: the trail floats left, the chips flow past it right-aligned, so they share that line and spill one at a time when it is full.
rpietzsch
marked this pull request as draft
September 8, 2026 10:25
The header override gated the search button and dialog on "material/search" in config.plugins - the entry point name mkdocs-material registers. Zensical registers the same plugin as "search", so the condition never matched and the block was skipped silently, while the 4.5 MB index and the search worker were still built and shipped on every page. Condition taken from Zensical's own partials/header.html.
…ensical-breadcrumbs
nav: add breadcrumb trail
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
2 participants
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.
No description provided.