Skip to content

Development

The theme is in iscc/zensical-iscc. This site comes from the same repository, so each theme change shows here first.

Commands

uv sync                  # install the dev dependencies
uv run prek install      # install the git hooks, one time for each clone
uv run poe all           # format, type check, test
uv run poe ci            # run all gates without changes to files, with the check of this site
uv run poe docs          # build this site and serve it on 127.0.0.1:45472

The tests build copies of this site with Zensical. They need 100% branch coverage. After each change to the theme or to the Zensical version, look at this site in both color schemes.

Layout

Path Contents
zensical_iscc/theme/mkdocs_theme.yml Theme defaults: fonts off, favicon, features, palette
zensical_iscc/theme/main.html Brand stylesheets, social metadata, Markdown link, redirects, widget settings
zensical_iscc/theme/partials/logo.html The project logo and the ISCC logo in both color versions
zensical_iscc/theme/partials/header.html The Zensical header plus the "Projects" menu. A test compares it with the Zensical header
zensical_iscc/theme/partials/projects.html The "Projects" menu, from [[project.extra.iscc.related]]
zensical_iscc/theme/partials/copyright.html The footer content: ISCC logo, copyright text, shared ISCC links, social links
zensical_iscc/theme/partials/social.html Empty. copyright.html shows the social links, also without extra.social
zensical_iscc/theme/partials/integrations/analytics* Plausible as the default analytics provider
zensical_iscc/theme/assets/iscc/theme.css Maps the tokens to the Zensical variables and styles the components
zensical_iscc/theme/assets/iscc/tokens/, fonts/, logos/ Copies of the ISCC brand assets: tokens, Readex Pro and JetBrains Mono, logos
zensical_iscc/theme/assets/iscc/vendor/glightbox/ GLightbox 3.3.1, not changed
zensical_iscc/theme/assets/iscc/copypage.js "Copy page", "View as Markdown", "Edit on GitHub"
zensical_iscc/theme/assets/iscc/copilot.js, copilot.css The loader and styles of the iscc.ai chat widget
zensical_iscc/cli.py, markdown.py, check.py, project.py The zensical-iscc command
zensical_iscc/project_logo.py Draws the project logo
zensical.toml, docs/ This site and the reference configuration
CHANGELOG.md Release notes. A git hook copies them to docs/changelog.md
skills/iscc-docs-theme/ The setup skill and the docs workflow template for sites
skills/docs-for-agents/ The skill for the "For Coding Agents" page
.claude-plugin/marketplace.json The plugin marketplace. Its one entry points to skills/
skills/.claude-plugin/ The plugin manifest and its icon. The plugin version is the package version
tests/fixtures/project-logos/ Reference project logos. project_logo.py must make the same files, byte for byte

Zensical copies all files of the theme directory that are not templates into the built site, so theme/ contains no Python code. The mkdocs.themes entry point names an object whose __file__ is in theme/.

Copied files

Some files are copies. Update them from their source. Do not edit them here.

Files Source
Tokens, fonts, logos, favicons, grain.png, the app tile, the plugin icon ISCC sources that are not public
tests/fixtures/project-logos/ The ISCC brand assets. Port changes of the project logo construction to project_logo.py
skills/docs-for-agents/SKILL.md plugins/docs-for-agents/ in titusz/skills
docs/changelog.md CHANGELOG.md, written by the changelog git hook

Upgrade Zensical

pyproject.toml pins one Zensical version, because the theme overrides Zensical templates. To upgrade:

  1. Change the pin.
  2. Build this site. Compare both color schemes with the previous version in a browser.
  3. Run the tests.
  4. Release.

A test compares partials/header.html with the Zensical header. If Zensical changes its header, the test fails.

Release

  1. In CHANGELOG.md, change "Unreleased" to the version and the date. Commit the copy that the hook writes.
  2. Set version in pyproject.toml and in skills/.claude-plugin/plugin.json. A test makes sure that both versions are equal. Users get skill changes only when the plugin version changes, which is at each release.
  3. Merge to main.
  4. Tag and publish the release. In the release notes, give the Zensical version that the release pins:
git tag vX.Y.Z && git push origin vX.Y.Z
gh release create vX.Y.Z --title vX.Y.Z --notes "..."

Sites change to the release with the tag in their [tool.uv.sources]. This site deploys from main to GitHub Pages on each push that changes it.

License

The code, templates and stylesheets are licensed under the Apache License 2.0. The bundled fonts are licensed under the SIL Open Font License and GLightbox under the MIT License. The ISCC logos and symbols are brand assets of the ISCC Foundation for use on ISCC sites.