- New `mdcms serve` command: local preview server with SPA clean-URL
fallback. Unknown extension-less paths (e.g. /section-id) are served
index.html so reloads and shared clean URLs work; paths with an
extension still 404, preserving the renderer's category-variant
fallback. Serves .md as text/markdown and .yml as text/yaml.
Options: [name], --path, --port (default 8800), --bind.
- New docs/hosting.md: explains why clean URLs 404 on plain static
hosts and documents the fix per environment (mdcms serve, service
worker, GitHub Pages 404.html, Netlify/Cloudflare _redirects, nginx,
Apache, Caddy), plus a standalone Python preview script.
- Update stale boot error message in index.html to point at
`mdcms serve` instead of the removed "option 8".
- Update CLAUDE.md command table and local-preview note.
https://claude.ai/code/session_018KXUwmSNMGF2UBywTChCcS
Renderer (app/index.html):
- navigateTo now pushes a history entry for user navigations (pushState),
while the initial load, back/forward (popstate/hashchange), and category
re-renders still replaceState. The browser Back button now returns to the
previous page instead of leaving the site.
Service worker (mdcms.py generator + app/service-worker.js):
- Serve the cached index.html app shell for navigation requests. Reloading a
clean URL like /section-id previously 404'd on the static host before any
JavaScript ran; the shell fallback lets the client-side router resolve the
path. Also makes pretty-URL reloads work offline.
https://claude.ai/code/session_018KXUwmSNMGF2UBywTChCcS
Renderer (app/index.html):
- Guard the router so navigateTo and the hashchange/popstate handlers only
load relative .md paths (isSafePagePath). Blocks fetching attacker-
controlled external URLs injected via the location hash.
- Stop treating in-page heading anchors (#heading) as page files, which
previously replaced the page with a 404.
- HTML-escape meta.title, link href/title attributes, not-found/offline
messages, and the icon fallback img; block javascript:/data: hrefs via
safeUrl.
- Hydrate mdcms tags nested inside tabs/accordions/callouts.
- Configure marked once instead of on every render.
- Validate stored theme value; fix text-align center; resolve per-category
offline message after categories initialise.
CLI (mdcms.py):
- Restore CDN_DEPS, _WOFF2_URL_RE, _fetch_bunny_fonts, _patch_index_html so
fetch-deps no longer raises NameError.
- Compare site markers against SITE_FORMAT_VERSION with zero-padded version
comparison, removing the spurious "update available" warning on v0.6 sites.
- Bump CLI to 0.6.1.
https://claude.ai/code/session_018KXUwmSNMGF2UBywTChCcS
mdcms build now calls generate_site_manifest() at the end of every build,
writing mdcms.json to the site root. This file lists all deployable files
and empty directories, and is deployed alongside the site so any mdcms
user can register a copy of the site from its URL.
mdcms register now accepts a GitHub repo URL or plain HTTPS URL as PATH
or via --from. GitHub URLs try mdcms.json (raw content) first and fall
back to the Contents API tree-walk. Plain URLs require mdcms.json to be
present and fail with a clear error if it is not found.
- generate_site_manifest() added; called at end of run_build
- download_template(dest, source=None) dispatches on source type
- _parse_github_url() extracts owner/repo/branch/subpath from GitHub URLs
- _fetch_manifest() / _apply_manifest() handle the manifest protocol
- _download_tree_api() retained as GitHub Contents API fallback
- _http_get_github() carries Accept header for Contents API responses
- MANIFEST_FILENAME = "mdcms.json"; GITHUB_URL_RE added
- app/template-manifest.json replaced by app/mdcms.json
- register command: PATH accepts URL; --from option added
https://claude.ai/code/session_01Ai8xRvmrzdhuTKiRQ2fnn9
Replace the GitHub Contents API tree-walk with a flat manifest approach.
template-manifest.json lists every file and empty directory in the starter
template; download_template() fetches the manifest then pulls each file
directly as a raw URL, sidestepping git API rate limits and making the
template hostable from any HTTP source.
- GITHUB_CONTENTS_API / _github_get / _download_tree removed
- TEMPLATE_BASE_URL + TEMPLATE_MANIFEST constants added
- _http_get() replaces _github_get() (generic, no GitHub headers)
- download_template() accepts optional base_url for custom sources
- app/template-manifest.json added (v0.4, 35 files, 2 empty dirs)
- Generated files (manifest.json, service-worker.js, search.json)
excluded from manifest — they belong to mdcms build output, not
the starter template
https://claude.ai/code/session_01Ai8xRvmrzdhuTKiRQ2fnn9
fetchPageFile now rejects text/html responses so servers with SPA routing
(e.g. Cloudflare Pages with /* /index.html 200) no longer trick the renderer
into treating a fallback index.html as a found markdown file. Category-variant
pages (page.current.md with no plain page.md) now fall through correctly to
their variant URL.
mdcms build now writes a self-unregistering service-worker.js when pwa: no,
evicting any stale caching worker left over from a previous pwa: yes build.
manifest.json is also removed when pwa: no.
https://claude.ai/code/session_01Xs5GyREFhjWxhS1UhW2wA8
A YAML parse error in config.yml (e.g. a stray tab character) caused
read_config to swallow the exception and return {}, disabling categories
and producing a broken nav.yml with no variants fields and wrong filenames.
read_config now raises ClickException on both OSError and YAMLError.
Documented in docs/knownbugs.md and docs/unreleased.md.
https://claude.ai/code/session_01Xs5GyREFhjWxhS1UhW2wA8
mdcms build now writes the sitename from config.yml into the <title> tag
of index.html. WhatsApp, Slack, and other link-preview crawlers read the
static HTML without executing JavaScript, so the title must be correct in
the raw file. Previously it was blank (or "MD-CMS" in older templates).
Pages without a category suffix still map to the default category.
Only posts/ files without a suffix get uncategorized: true in nav.yml
and category: null in search.json.
https://claude.ai/code/session_01EzU13EL8D5Ud2ngQUKDj9e
Files without a category suffix (e.g. post.md alongside post.en.md)
previously only appeared in the default category. They now appear in
every category, so untranslated content is always visible.
- mdcms.py: nav entries with a bare variant get `uncategorized: true`;
search.json keeps `category: null` instead of mapping to default code
- index.html: pageShouldDisplay, posts filter, and category dropdown
all treat uncategorized/null-category items as universally visible
https://claude.ai/code/session_01EzU13EL8D5Ud2ngQUKDj9e
- mdcms.py: expand abbreviated notice to full boilerplate
- app/index.html: fix version in comment header (v0.3.8 → v0.4)
- app/config.yml: add missing final two lines of notice
- app/theme.yml: add full licence notice (was missing entirely)
https://claude.ai/code/session_01UP8Wo2CKPNhvvTkzX48CWF
- mdcms.py: CLI_VERSION 0.4.0, updated docstring and comment
- pyproject.toml: version 0.4.0
- app/index.html: site format marker → mdcms v0.4
- app/config.yml: site format marker → mdcms v0.4
- app/theme.yml: add site format marker mdcms v0.4
https://claude.ai/code/session_01UP8Wo2CKPNhvvTkzX48CWF
- Add generate_pwa(): builds manifest.json (name, short_name, theme_color,
standalone display, favicon icon) and service-worker.js with a
cache-first strategy; cache name is versioned by a hash of the precache
file list so new builds automatically invalidate old caches; precache
list covers index.html, config.yml, nav.yml, search.json, theme file,
and all pages/posts/assets
- Call generate_pwa() from run_build() when pwa: yes/true in config.yml
- index.html: add <link rel="manifest"> and SW registration script in
<head>; both silently no-op when the generated files are absent
- index.html boot(): write offline-message from config to localStorage
on every load so the message survives cache eviction
- index.html navigateTo(): show localStorage offline message when a page
fetch fails instead of the generic not-found message
- Update CLAUDE.md with PWA config key reference
https://claude.ai/code/session_015XtsgTMi8UtmgxEgb5Qt2c
- Add renderTocTag(): groups visible pages by section in section sort
order; sorts pages within each section by sort then filename; excludes
current page, draft sections, and category-invisible pages; renders
section headings and linked page lists; replaces the tag placeholder
- Add toc dispatch in hydrateMdcmsTags()
- Add .mdcms-toc, .mdcms-toc-section, .mdcms-toc-list CSS
https://claude.ai/code/session_015XtsgTMi8UtmgxEgb5Qt2c
- Add validate_assets(): scans config.yml and theme.yml recursively for
string values starting with assets/, and all markdown files in pages/
and posts/ via regex; deduplicates by (path, source) before checking
- Add _collect_yaml_assets() helper for recursive YAML traversal
- Call validate_assets() in run_build() after writing nav.yml and
search.json; prints yellow warnings for each missing asset, build
continues on all warnings
https://claude.ai/code/session_015XtsgTMi8UtmgxEgb5Qt2c
- CLI_VERSION → 0.3.1, CLI_RELEASE_DATE → 10 May 2026
- Replace click.version_option with custom callback that prints version
+ release date, then fetches docs/banner/v{VERSION}.txt from GitHub
and prints it; falls back to a "no online information" message on 404
or network error
- Add versioning rule to CLAUDE.md
https://claude.ai/code/session_015XtsgTMi8UtmgxEgb5Qt2c
date and datetime were overlapping with created. Only created is now
read by the scanner and emitted in search.json; modified is also
included in search.json output alongside it.
https://claude.ai/code/session_013A4egzphocyto9bvZ76dxf
- Replace interactive TUI with click-based subcommands:
register, delete, view, build
- build accepts NAME (registry), --path, or CWD for GitHub Actions use
- Switch to PyYAML for frontmatter and nav.yml parsing
- Add pyproject.toml with click + PyYAML deps and mdcms entry point
- Add v0.3 version marker to app/config.yml and app/index.html
- Registry moves to ~/.config/mdcms/sites.json (XDG-compliant)
- Project root is now the directory containing index.html (no website/ subdir)
- register auto-downloads template from GitHub if no site found
https://claude.ai/code/session_01MqEqGhP1guGx5VuFsLaws2
