中文说明
Updated: 2026-07-23
Maintainer: mdPress product team
v0.1.0 ██████████████████████████████████████████ released
v0.2.0 ██████████████████████████████████████████ released (2026-03-19)
v0.3.0 ██████████████████████████████████████████ released (2026-03-19)
v0.3.1 ██████████████████████████████████████████ released (2026-03-19)
v0.4.0 ██████████████████████████████████████████ released (2026-03-19)
v0.4.1 ██████████████████████████████████████████ released (2026-03-19)
v0.4.2 ██████████████████████████████████████████ released (2026-03-19)
v0.4.3 ██████████████████████████████████████████ released (2026-03-19)
v0.5.0 ██████████████████████████████████████████ released (2026-03-20)
v0.5.1 ██████████████████████████████████████████ released (2026-03-21)
v0.5.2 ██████████████████████████████████████████ released (2026-03-22)
v0.5.3 ██████████████████████████████████████████ released (2026-03-23)
v0.5.4 ██████████████████████████████████████████ released (2026-03-23)
v0.6.0 ██████████████████████████████████████████ released (2026-03-23)
v0.6.1 ██████████████████████████████████████████ released (2026-03-24)
v0.6.2 ██████████████████████████████████████████ released (2026-03-25)
v0.6.3 ██████████████████████████████████████████ released (2026-03-25)
v0.6.4 ██████████████████████████████████████████ released (2026-03-26)
v0.6.5 ██████████████████████████████████████████ released (2026-03-27)
v0.6.6 ██████████████████████████████████████████ released (2026-03-27)
v0.6.7 ██████████████████████████████████████████ released (2026-03-27)
v0.6.8 ██████████████████████████████████████████ released (2026-03-28)
v0.6.9 ██████████████████████████████████████████ released (2026-03-28)
v0.7.0 ██████████████████████████████████████████ released (2026-03-28)
v0.7.1 ██████████████████████████████████████████ released (2026-03-29)
v0.7.2 ██████████████████████████████████████████ released (2026-03-30)
v0.7.3 ██████████████████████████████████████████ released (2026-04-01)
v0.7.4 ██████████████████████████████████████████ released (2026-04-04)
v0.7.5 ██████████████████████████████████████████ released (2026-04-06)
v0.7.6 ██████████████████████████████████████████ released (2026-04-13)
v0.7.7 ██████████████████████████████████████████ released (2026-04-15)
v0.7.8 ██████████████████████████████████████████ released (2026-04-18)
v0.7.9 ██████████████████████████████████████████ released (2026-04-19)
v0.7.10 ██████████████████████████████████████████ released (2026-05-08)
v0.7.11 ██████████████████████████████████████████ released (2026-06-17)
v0.7.12 ██████████████████████████████████████████ released (2026-07-05)
v0.7.13 ██████████████████████████████████████████ released (2026-07-05)
v0.7.14 ██████████████████████████████████████████ released (2026-07-10)
v0.7.15 ██████████████████████████████████████████ released (2026-07-22)
v0.8.0 ██████████████████████████████████████████ released (2026-07-23)
v0.8.1 ██████████████████████████████████████████ released (2026-07-23)
v0.8.2 ██████████████████████████████████████████ released (2026-07-24)
v1.0.0 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ planned (target: 2027-Q1)
Release date: 2026-03
Theme: core build pipeline
v0.1.0 established the base architecture of mdPress and shipped a complete Markdown-to-PDF workflow.
| Feature | Description |
|---|
| Markdown -> PDF conversion | Built on Chromium rendering for professional-quality output |
| Full GFM support | Tables, task lists, footnotes, strikethrough, and autolinks |
book.yaml config system | Book metadata, chapters, styles, and output options |
| Auto-generated TOC | Built from heading hierarchy with page numbers and links |
| Cover page generation | Title, author, version, date, image, and background support |
| Syntax highlighting | Powered by Chroma with 100+ languages |
| Multi-chapter assembly | Nested chapter definitions supported |
| Theme system | Built-in technical, elegant, and minimal themes |
| Image handling | Local and remote images embedded as base64 when needed |
| Cross references | Figure and table IDs plus {{ref:id}} support |
| Headers and footers | Template variables for page number, chapter title, and book title |
mdpress init | Project initialization with sample files |
mdpress themes | Theme inspection commands |
| Multiple page sizes | A4, A5, Letter, Legal, and B5 |
| Custom CSS | External CSS overrides |
GLOSSARY.md | Glossary highlighting and appendix generation |
| CI/CD integration | GitHub Actions workflow support |
Release date: 2026-03-19
Theme: lower the barrier to entry and expand output capability
v0.2.0 moves mdPress from a PDF-first generator toward a multi-format publishing platform, with a strong focus on usability and migration compatibility.
| Feature | Priority | Description |
|---|
| Single-page HTML output | P0 | --format html generates a self-contained HTML document |
| GitHub repository sources | P0 | Build directly from GitHub URLs without a local clone |
SUMMARY.md compatibility | P0 | Support GitBook-style chapter definition files |
| Zero-config auto-discovery | P0 | Scan Markdown files automatically when book.yaml is absent |
Live preview via serve | P0 | Local HTTP server with file watching and WebSocket reload |
site output clarification | P0 | Sharpen the responsibility split between html, serve, and site |
doctor command | P1 | Quick environment and project-readiness checks |
| Improvement | Description |
|---|
--format | Allow pdf, html, and comma-separated multi-format builds |
--output | Provide a unified output path or prefix for builds |
| Better errors | Attach actionable remediation hints to errors |
| CI/CD templates | Ship GitHub Actions and GitLab CI templates |
2026-03-19 v0.2.0 release ✓
Release date: 2026-03-19
Theme: broader output support and extensibility
v0.3.0 expanded mdPress into a true multi-format publishing platform with a plugin architecture and first-class support for math and diagrams.
| Feature | Priority | Description |
|---|
| ePub 3 output | P0 | Standard ePub 3 books with cover, TOC, and metadata |
| Plugin system | P0 | Full plugin lifecycle with external process loading and hook registration |
| KaTeX math support | P1 | Inline ($...$) and block ($$...$$) LaTeX math via KaTeX |
| Mermaid diagram support | P1 | Native Mermaid rendering in all HTML-based outputs; automatic Mermaid syntax checks in validate |
| GitBook migration tool | P1 | mdpress migrate converts GitBook projects to mdPress format |
Multi-format all shorthand | P1 | --format all builds PDF, HTML, site, and ePub in one command |
| GitHub Actions template | P2 | Pre-built workflow for automated book builds in CI |
| Fix | Description |
|---|
| CJK PDF font embedding | Inject @font-face rules with file:// URLs so Chrome can embed CJK glyphs |
| TOC depth control | output.toc_max_depth config to limit heading depth in table of contents |
| Smart output filename | Derive output filename from book title instead of defaulting to output.pdf |
| Regexp performance | Promote regexp compilation to package level in crossref, glossary, markdown, and image processing |
| Git author fallback | Fall back to git config user.name when no author is specified |
Release date: 2026-03-19
Theme: performance and zero-dependency PDF
| Feature | Priority | Description |
|---|
| Typst backend | P2 | Use Typst instead of Chromium for true zero-external-dependency PDF |
| Incremental builds | P2 | Rebuild only changed chapters |
| Parallel builds | P2 | Use multiple CPU cores for chapter parsing and rendering |
| PDF watermarking | P2 | Text watermarks with opacity control |
| Custom PDF margins | P2 | Per-side margin configuration in multiple units |
| PDF bookmarks | P2 | Auto-generated from heading hierarchy for better navigation |
| Build cache | P2 | File-hash-based cache to avoid redundant work |
| PlantUML support | P2 | Auto-detect and render PlantUML diagrams in code blocks |
| Dimension | Chromium backend | Typst backend |
|---|
| External dependency | Requires Chrome or Chromium | None, if bundled or invoked via Typst CLI |
| Layout quality | Excellent web-standard rendering | Excellent professional typesetting |
| CJK support | Strong | Strong |
| Build speed | Moderate due to browser startup | Faster native compilation path |
| Binary size | Small without Chromium | Likely larger if Typst is bundled |
| CSS compatibility | Full | Requires adaptation into Typst styling |
CLI direction (implemented):
--format pdf uses Chromium (default PDF backend)--format typst uses Typst as an alternative PDF backend
.mdpress-cache/
├── manifest.json
├── ch01.html
├── ch02.html
└── ...
Expected flow:
- Compute SHA-256 for every chapter
- Compare hashes with
manifest.json
- Rebuild only changed chapters
- Merge cached chapters with newly compiled chapters
- Produce the final output
Expected payoff: rebuilding a 500-page book after editing one chapter should drop from roughly 120 seconds to under 10 seconds.
Release date: 2026-03-20
Theme: offline capability and test coverage foundation
v0.5.0 closes the most critical gap for enterprise users (offline PlantUML rendering), repairs the release CI pipeline, and establishes a golden test framework to prevent backend regressions.
| Feature | Priority | Description |
|---|
| PlantUML local rendering | P1 | renderLocal() invokes local plantuml CLI or plantuml.jar; enabled via plantuml.use_local: true |
| Golden test framework | P2 | Snapshot-based regression tests in tests/golden/; regenerate with -update flag |
| Doctor PlantUML check | P1 | mdpress doctor detects local PlantUML availability and prints install hints |
| CI Node.js 24 upgrade | P0 | goreleaser-action@v7, codecov-action@v5 ahead of 2026-06-02 deadline |
| Release CI Docker fix | P0 | Removed stale Docker Hub login step; images publish exclusively to GHCR |
| Package | v0.4.3 | v0.5.0 | Delta |
|---|
internal/plantuml | 54.8% | 75%+ | +20 pp |
internal/source | 41.2% | 62%+ | +21 pp |
cmd | 47.7% | 60%+ | +12 pp |
| Overall | 62.3% | ≥ 68% | +6 pp |
Release date: 2026-03-21
Theme: UI refinement and bug fixes
v0.5.1 delivers accordion-style sidebar navigation improvements and fixes critical context propagation issues affecting PlantUML rendering, SUMMARY.md title handling, and migration workflows.
| Feature | Priority | Description |
|---|
| Accordion sidebar navigation | P1 | Expanding a chapter section automatically collapses sibling sections at the same level for cleaner GitBook-like navigation |
| Smoother sidebar transitions | P2 | CSS transitions upgraded to Material Design easing curves for better expand/collapse animations |
| Fix | Priority | Description |
|---|
| PlantUML context propagation | P0 | Replaced context.Background() with caller-provided context, ensuring build timeout and cancellation signals propagate correctly |
| Generic SUMMARY.md title filtering | P0 | Titles like "在线阅读", "Read Online", and "Contents" now correctly recognized as generic navigation headings |
| book.json title priority | P1 | When book.json provides a title, it is no longer overwritten by README.md inference during auto-discovery |
Missing migrate command in README | P1 | Added the migrate command to the "All Commands" table in both English and Chinese READMEs |
| GitLab CI lint version mismatch | P2 | Aligned golangci-lint from v2.1 to v2.11.3 to match GitHub Actions |
| Misspelling in completion command | P2 | Fixed behaviour → behavior in comment |
Release date: 2026-03-22
Theme: Cross-platform robustness and CI reliability
v0.5.2 improves Windows support with plugin executable resolution via PATHEXT, fixes cross-platform test failures, and hardens the CI supply chain by upgrading all GitHub Actions to their latest major versions.
| Feature | Priority | Description |
|---|
| Windows plugin executable resolution | P1 | Plugin paths without extensions auto-resolve via PATHEXT (.exe, .bat, .cmd) |
| Search focus style and a11y traps | P2 | Improved keyboard accessibility with visible focus indicators |
| Fix | Priority | Description |
|---|
| Cross-platform test paths | P0 | Replaced hardcoded Unix paths with t.TempDir() in config tests, fixing Windows CI |
| Codecov action parameter | P1 | Corrected file to files for codecov-action@v5 |
| Dependabot config syntax | P1 | Fixed invalid pull-requests.max-number to open-pull-requests-limit |
| ePub test resource leak | P2 | Added missing reader.Close() in epub test |
Release date: 2026-03-23
Theme: Bug fixes and documentation alignment
v0.5.3 fixes critical code block rendering issues in site output and updates project documentation.
| Fix | Priority | Description |
|---|
| Invisible code block text | P0 | Chroma syntax highlighter injected inline style="background-color:#fff" on <pre> tags, making code blocks unreadable. Fix strips chroma's inline style during post-processing. |
| Site code block color scheme | P1 | Changed site output code blocks from dark theme to light theme (#f6f8fa background, #24292e text) matching the chroma "github" palette |
| Change | Description |
|---|
| Documentation updates | Updated ARCHITECTURE docs version, fixed ROADMAP version ordering, added Typst format to README table |
| Removed stale NEXT-STEPS.md | Deleted outdated planning document that referenced v0.4.3 as latest |
Release date: 2026-03-23
Theme: Rich site features and security hardening
v0.5.4 is a major feature release for the site output format, adding client-side full-text search, dark mode, breadcrumb navigation, page TOC, code copy buttons, and SEO optimization. It also fixes several bugs including ePub resource leaks, UTF-8 truncation issues, and a symlink-based path traversal vulnerability in the dev server.
| Feature | Priority | Description |
|---|
| Full-text search | P0 | Client-side search with Cmd/Ctrl+K shortcut, keyboard navigation, and result highlighting |
| Dark mode toggle | P0 | Three-way theme switcher (light/dark/system) with localStorage persistence |
| SEO meta tags | P1 | Auto-generated description and Open Graph tags per page |
| Sitemap generation | P1 | sitemap.xml for search engine indexing |
| Breadcrumb navigation | P1 | Page hierarchy trail on each site page |
| Page TOC sidebar | P1 | "On this page" sidebar with scroll-spy via IntersectionObserver |
| Code block copy button | P1 | Hover-to-reveal copy button with clipboard integration |
| Sidebar collapse | P2 | Desktop sidebar collapsible with persistent state |
| Lazy loading images | P2 | loading="lazy" on all <img> tags automatically |
| CJK heading IDs | P1 | Custom heading ID transformer that preserves Unicode letters |
| Fix | Priority | Description |
|---|
| ePub zip writer resource leak | P1 | Added defer w.Close() for all error paths |
| UTF-8 truncation in SVG cover | P1 | Rune-based truncation replaces byte-based slicing |
| SVG XML attribute escaping | P2 | Added " and ' entity escaping |
| Symlink path traversal | P1 | filepath.EvalSymlinks() added to serve path check |
| Scroll behavior regression | P2 | Fixed ternary always returning 'auto' instead of 'smooth' |
| Description meta truncation | P2 | Rune-based truncation for multi-byte character safety |
Release date: 2026-03-23
Theme: production readiness foundation
v0.6.0 bridges the gap between feature-driven development (v0.1–v0.5) and the production-ready v1.0.0 release.
| Feature | Priority | Description |
|---|
mdpress upgrade command | P0 | Self-upgrade from GitHub releases with platform detection, SHA-256 checksum verification, and --check dry-run mode |
Enhanced mdpress doctor | P0 | Six new environment checks: Go version (≥1.26), Git availability, network connectivity, disk space, CJK font detection, and plugin health; new --verbose flag |
| Bilingual user manual | P0 | Complete Chinese + English user manual (60+ Markdown files) built with mdPress itself |
ParseVersionPart utility | P2 | Reusable version-string parser for doctor and upgrade commands |
| Improvement | Priority | Description |
|---|
| Path traversal hardening | P1 | LocalSource.Prepare() validates subdirectory paths against traversal attacks |
| Cross-platform path handling | P1 | filepath.Join replaces string concatenation in HasLangsFile for Windows compatibility |
| Documentation updates | P2 | upgrade command added to README command table (EN + ZH) and COMMANDS docs |
| Fix | Priority | Description |
|---|
| Lint cleanup | P2 | Removed duplicate test helpers and unused imports across cmd/*_test.go |
| Chinese text truncation test | P2 | Increased input size so the ≥160-rune truncation path is exercised |
- 1,500+ new test lines across 12 files
- Full coverage of
upgrade command: version comparison, asset selection, download, and binary replacement
- Expanded
doctor, cmd, themes, quickstart, validate tests
- Comprehensive utility function tests for
file, cjk, image packages
- Expanded plugin lifecycle and error-path tests
Release date: 2026-03-24
Theme: quality and consistency
v0.6.1 is a patch release that fixes bugs discovered in v0.6.0 and improves documentation coverage.
| Fix | Priority | Description |
|---|
| Typst timeout configuration | P0 | compileToPDF() now uses the configured g.timeout instead of a hardcoded 120-second value |
| Format validation for Typst | P0 | Added typst to validFormats so book.yaml accepts typst as an output format |
| Git branch name validation | P1 | Branch name regex now requires leading alphanumeric character to prevent CLI flag injection |
| ePub cleanup error handling | P1 | os.Remove errors on failed builds are now logged instead of silently ignored |
| Error message consistency | P2 | Replaced remaining Chinese error messages with English in parser.go and crossref.go |
| GoReleaser Homebrew URL case | P2 | Corrected mdPress to mdpress in the Homebrew Cask verified URL |
| Gosec exclusion ordering | P2 | Sorted gosec rule exclusions numerically in .golangci.yml |
| Change | Description |
|---|
| Doctor command docs | Updated doctor.md and doctor_zh.md with all v0.6.0 environment checks |
| User manual links in README | Added links to the bilingual user manual in both READMEs |
version command in COMMANDS | Added the version command to the command matrix and hierarchy diagram |
| ROADMAP update | Added v0.6.0 and v0.6.1 release notes |
.gitignore enhancement | Added .agent/, .env, and credential file patterns |
Release date: 2026-03-25
Theme: security and correctness
v0.6.2 is a security-focused release that hardens the preview server, upgrade command, image handling, and theme CSS against injection and traversal attacks. It also fixes numerous parser, cache, and rendering bugs.
| Fix | Priority | Description |
|---|
| WebSocket origin validation | P0 | Preview server validates Origin header against Host to prevent cross-origin hijacking |
| Upgrade URL domain validation | P0 | Binary downloads verify the URL points to github.com or *.githubusercontent.com |
| Absolute image path rejection | P1 | resolveLocalImagePath rejects absolute paths to prevent reading arbitrary local files |
| Theme CSS injection prevention | P1 | Theme color and font values validated against unsafe characters before CSS output |
| CSS color pattern tightened | P1 | rgb()/hsl() patterns restrict content to safe characters |
| Security headers | P2 | Preview server sets X-Content-Type-Options: nosniff and X-Frame-Options: DENY |
| Fix | Priority | Description |
|---|
| Chapter cache key mismatch | P0 | Cache key uses same fallback logic as parser, preventing stale hits |
| PlantUML encoding | P0 | Correct raw deflate and PlantUML custom 6-bit encoding alphabet |
| Heading ID race condition | P0 | Each Transform call uses a local usedIDs map instead of shared state |
| Path traversal via book.json | P1 | safeJoin() rejects absolute and escaping paths |
| Typst font size fallback | P1 | Parse failures fall back to 12pt instead of invisible 0.0pt |
| Glossary double-wrapping | P1 | Overlapping terms no longer create nested <span> tags |
| UTF-8 title capitalization | P1 | Uses []rune + unicode.ToUpper for multi-byte first characters |
| Typst template injection | P1 | User content with {{ }} no longer panics or injects code |
| Change | Description |
|---|
| Triple config load eliminated | doctor loads config once and passes it through |
| Dead code removed | Unused CacheStatistics, no-op convertCodeSpans, duplicate fileExists removed |
| Glossary regex hoisted | skipPattern compiled once at package level |
| Search index optimization | utf8.RuneCountInString() replaces len([]rune(...)) |
| Change | Description |
|---|
| validate command | Documented the --report flag |
| completion command | Corrected --no-descriptions support from bash/zsh to bash/fish |
| build command | Documented that --format all expands to pdf,html,site,epub,typst |
| upgrade command | Removed fabricated exit codes section |
Release date: 2026-03-25
Theme: security and search UX
v0.6.3 hardens the codebase against SSRF, XSS, path traversal, and template injection attacks. It also redesigns the search UI as a right-side panel.
| Fix | Priority | Description |
|---|
| SSRF prevention for PlantUML | P0 | Validates PlantUML server URLs against private/loopback IPs via DNS resolution |
| Mermaid XSS fix | P1 | Re-escapes HTML entities after unescaping in Mermaid code blocks |
| EPUB path traversal prevention | P1 | Rejects absolute image paths and validates relative paths stay within source directory |
| Tar path traversal prevention | P1 | Skips tar entries containing .. during upgrade extraction |
| Template injection prevention | P1 | Strips {{ and }} from Typst metadata and dimension fields |
| Config field validation | P1 | Validates font_family, font_size, and code_theme against injection patterns |
| Custom CSS size limit | P2 | Limits custom CSS file reads to 1 MB |
| URL scheme validation | P2 | openBrowser only allows http and https schemes |
| Fix | Priority | Description |
|---|
| Search broken on subpages | P0 | Search index fetched with absolute path instead of relative |
| Search result links wrong | P0 | Search result hrefs use absolute paths for correct navigation |
| Off-by-one bounds check | P1 | Fixed submatch access in EPUB and image regex |
| Unchecked type assertion | P1 | PlantUML cache uses comma-ok pattern |
| GitHub tempdir leak | P1 | Prepare() cleans up temp directory on validation failure |
| Change | Description |
|---|
| Search redesigned as right-side panel | Search opens as a GitBook-style right panel instead of a modal overlay |
| Defensive slice copy | Plugins() returns a copy to prevent external mutation |
| Goroutine panic recovery | Image prefetch goroutines recover from panics |
Release date: 2026-03-26
Theme: PDF image and diagram rendering
v0.6.4 fixes critical PDF rendering issues including missing images, broken Mermaid diagrams, invisible SVG badge text, and incorrect layout.
| Fix | Priority | Description |
|---|
| PDF images not rendering | P0 | Strip loading="lazy" from images before PDF generation |
| Mermaid diagrams missing text | P0 | Remove HTML re-escaping that broke arrows and tags in Mermaid |
| Mermaid digits/Latin missing in PDF | P1 | Add Latin fonts before CJK fonts in Mermaid SVG CSS rules |
| SVG badge CJK text missing in PDF | P1 | Inline CJK-containing SVGs with embedded font-face |
| Badge images stacked vertically | P1 | Block display only for standalone images |
| mdPress docs injected into PDF | P1 | Filter CHANGELOG.md, CONTRIBUTING.md, LICENSE.md from auto-discovery |
| Cover version defaults to 1.0.0 | P1 | Read version from book.json with git describe fallback |
| Duplicate branding on cover | P2 | Remove inline brand footer from cover template |
Release date: 2026-03-27
Theme: security defense-in-depth and correctness
v0.6.5 adds five security hardening measures across the plugin system, Mermaid renderer, Typst backend, upgrade pipeline, and git integration. It also fixes GitBook migration errors and search index performance.
| Fix | Priority | Description |
|---|
| Plugin path traversal enforced | P0 | Relative plugin paths resolving outside the project directory are now rejected instead of only logging a warning |
| Mermaid XSS defense-in-depth | P1 | Strip <script> tags and event handler attributes from Mermaid diagram content after HTML unescaping |
| Typst output capture bounded | P1 | Limit captured stdout/stderr from typst compile to 1 MB, preventing OOM from malicious documents |
| Upgrade redirect SSRF protection | P1 | Validate HTTP redirect targets during upgrade downloads to prevent SSRF via DNS poisoning |
| Git command timeouts | P1 | Add 5-second timeout to git describe and git config calls in auto-discovery to prevent indefinite blocking |
| Fix | Priority | Description |
|---|
| GitBook plugin migration errors | P1 | Skip GitBook npm plugins during book.json migration instead of generating invalid configs with missing paths |
| Search index heading snippets | P1 | Compute rune slice once per chapter instead of per heading, fixing O(N*M) allocation for chapters with many headings |
| Inline SVG badge height | P2 | Fix badge height mismatch between inline SVG and <img> rendering |
| Change | Description |
|---|
| Removed tautological tests | Remove tests that produced false coverage |
Release date: 2026-03-27
Theme: rendering correctness
v0.6.6 fixes duplicate chapter titles in PDF output and improves SUMMARY.md parsing to correctly handle inline links.
| Fix | Priority | Description |
|---|
| Duplicate chapter title in PDF | P0 | Sub-chapters using h2-h6 in Markdown had their heading duplicated because the deduplication logic only matched h1 tags; now matches any heading level |
| SUMMARY.md parsing picks up inline links | P0 | Navigation prose lines were incorrectly parsed as chapter entries; now only list items with a direct link are accepted |
| Feature | Priority | Description |
|---|
| Title mismatch warning | P1 | New book-title-mismatch rule warns when a SUMMARY.md title differs from the file's first heading; SUMMARY title takes precedence in rendered output |
Release date: 2026-03-27
Theme: PDF rendering correctness and security
v0.6.7 fixes duplicate PDF bookmarks from cover titles, README title deduplication for centered layouts, and ensures Mermaid diagrams fully render before PDF generation.
| Fix | Priority | Description |
|---|
| Cover title duplicate PDF bookmark | P0 | Cover page title changed from <h1> to styled <div>, preventing Chrome's outline generator from creating a bookmark that duplicates the first chapter entry |
| README title deduplication handles wrapped headings | P0 | stripDuplicateLeadingH1 now finds the first heading even when preceded by non-heading HTML (e.g., <div align="center">, badge images) |
| Mermaid diagrams fully render in PDF | P0 | Added a wait step (up to 15s) for mermaid.js to finish rendering all diagrams before Chrome prints to PDF |
| Fix | Priority | Description |
|---|
| Chrome CLI output capture bounded | P1 | Chrome CLI fallback limits captured stdout/stderr to 10 MB via chromeLimitedWriter, preventing OOM |
| Symlink-aware image path containment | P1 | resolveLocalImagePath and EPUB buildImageAssetFromSource resolve symlinks via filepath.EvalSymlinks before the containment check |
| Git argument injection hardened | P1 | discover.go git commands validated against flag injection |
Release date: 2026-03-28
Theme: correctness and test coverage
v0.6.8 improves Markdown parser thread safety, error wrapping in the upgrade pipeline, and GitHub source hardening. It also adds comprehensive test suites for checksum verification and SSRF redirect validation.
| Improvement | Priority | Description |
|---|
| Markdown parser thread safety | P1 | Remove unnecessary sync.RWMutex from parser; headings collected via local state, making concurrent Parse calls safe without locking |
| Error wrapping in upgrade | P2 | Use %w instead of %v for inner errors so callers can unwrap them |
| GitHub source hardening | P1 | Guard .gitattributes read with stat + size check to avoid reading oversized files |
| Test | Description |
|---|
| Checksum verification tests | Comprehensive test suite for upgrade binary checksum verification (valid match, mismatch, missing entry, case-insensitive hash, multiple formats) |
| SSRF redirect validation tests | Test coverage for PlantUML redirect target validation (localhost, loopback IP, .local suffix, empty hostname) |
Release date: 2026-03-28
Theme: PDF rendering correctness
v0.6.9 eliminates duplicate H1 bookmarks in PDF output by unconditionally stripping the leading <h1> from chapter content, since the template already renders the SUMMARY title as the chapter heading.
| Fix | Priority | Description |
|---|
| Eliminate duplicate H1 bookmarks in PDF | P0 | Always strip the leading <h1> from chapter content since the template already renders the SUMMARY title as <h1 class="chapter-title">. Previously, the content H1 was only removed when its text exactly matched the SUMMARY title; now it is removed unconditionally for H1 |
Theme: site output UX improvements
| Feature | Priority | Description |
|---|
| Previous/Next navigation | P0 | Bottom-of-page buttons linking to the previous and next chapters for continuous reading |
| "Built with mdPress" branding | P1 | Subtle footer link in site output; localized as "使用 mdPress 构建" for Chinese books |
| Collapsible sidebar sections | P2 | Expand/collapse arrows for chapters with sub-pages in the sidebar |
| Feature | Priority | Description |
|---|
| Sidebar chapter grouping | P2 | Support parts in book.yaml to group chapters under collapsible section headers (e.g. "Part 1: Getting Started") |
Release date: 2026-03-29
Theme: correctness, security, and format promotion
v0.7.1 fixes rendering bugs in heading regex matching, Typst code span conversion, and SVG inlining. It hardens PlantUML directive parsing and removes internal paths from the serve debug panel. It also promotes Typst to a first-class output format and adds site UX improvements.
| Feature | Priority | Description |
|---|
| Typst promoted to first-class output format | P0 | Typst PDF generation available as --format typst |
| Force flag for migrate command | P1 | Add --force flag to overwrite existing files during migration |
| Filename sanitization in init command | P1 | Sanitize filenames during project initialization |
| Post-install verification for upgrade | P1 | Verify binary integrity after upgrade installation |
| Site UX features | P1 | Add selection highlighting, pending navigation, and improved client-side navigation |
| Fix | Priority | Description |
|---|
| PlantUML directive and SVG sanitization hardened | P0 | Strengthen PlantUML directive parsing and SVG content sanitization |
| Internal paths removed from serve debug panel | P1 | Remove internal filesystem paths from the serve debug panel output |
| Fix | Priority | Description |
|---|
| Heading regex correct tag matching | P0 | Fix heading regex to match the correct heading level tag |
| Typst converter skips code spans | P0 | Prevent Typst markup conversion inside inline code spans |
| SVG inlining for nested SVGs | P1 | Fix SVG inlining when SVGs contain nested SVG elements |
| Typst builder uses raw Markdown | P1 | Fix Typst builder to pass raw Markdown instead of HTML |
| Windows path separator in test | P2 | Fix path separator handling for Windows compatibility |
| Improvement | Description |
|---|
| Doctor context and symlink handling | Improve doctor command with better context reporting and symlink-aware checks |
| PDF generator error handling | Check tmpFile.Close error in PDF generator |
Release date: 2026-03-30
Theme: code modernization and cross-platform reliability
v0.7.2 modernizes Go idioms across the codebase, migrating from deprecated APIs to modern equivalents and fixing Windows CI test failures.
| Change | Description |
|---|
| Modernize Go idioms | Migrate os.IsNotExist to errors.Is(err, fs.ErrNotExist), sort to slices package, == io.EOF to errors.Is |
| Remove redundant helper | Replace custom equalIntSlices with slices.Equal |
| Fix | Priority | Description |
|---|
| Stale error message in PDF generator | P1 | Fix error messages referencing old function name |
| Windows test failures in CI | P0 | Fix path handling in tests for Windows compatibility |
| Improvement | Description |
|---|
| Test assertions strengthened | Add missing assertions for return values in server and plugin tests |
| Documentation sync | Update ARCHITECTURE, ROADMAP, command docs, and manual versions |
Release date: 2026-04-01
Theme: security hardening and dependency updates
v0.7.3 addresses SSRF bypass vectors, upgrades the Go toolchain to 1.26.1, and modernizes octal literals and structured logging across the codebase.
| Fix | Priority | Description |
|---|
| Block SSRF via 0.0.0.0/8 range | P0 | Prevent server-side requests to "this network" addresses that reach localhost on Linux |
| Guard SUMMARY.md parsing against TOCTOU | P1 | Detect silent truncation when file grows between stat and read |
| Change | Description |
|---|
| Upgrade Go to 1.26.1 | Update minimum Go version and all dependencies |
| Use explicit octal literals | Migrate 0644/0755 to 0o644/0o755 across codebase |
| Use slog.Any for error logging | Preserve error type information in structured logs |
| Update CI to Go 1.26 | Bump GitHub Actions, GitLab CI, and Docker to Go 1.26 |
| Update Dockerfile to Alpine 3.23 | Use latest Alpine base image |
| Fix | Priority | Description |
|---|
| Handle deferred cleanup errors | P2 | Properly acknowledge discarded error returns in deferred cleanup calls |
| Fix CI cache path consistency | P2 | Add MDPRESS_CACHE_DIR env var to CI documentation examples |
| Fix stale plugin registry reference | P2 | Remove non-existent "plugin registry" link from migrate docs |
Release date: 2026-04-04
Theme: defense-in-depth security, dependency upgrades, and styling consistency
v0.7.4 hardens HTML/CSS sanitizers against advanced XSS vectors, eliminates TOCTOU race conditions in file operations, upgrades KaTeX and chroma, and adds missing figure/figcaption styles to standalone and EPUB outputs.
| Fix | Priority | Description |
|---|
| Harden Mermaid sanitizer regex | P0 | Fix dangerousTagPattern to handle > inside quoted attributes; expand jsURIPattern to replace entire href/src attributes |
| Block vbscript/protocol-relative URLs in CSS | P1 | Add vbscript: to CSS URL blocker; detect //evil.com protocol-relative URLs |
| Fix TOCTOU in build manifest | P1 | Replace stat+read with io.LimitReader in loadManifest and computeChapterHash |
| Add LimitReader to CopyFile | P1 | Defend against file growth between stat and copy with bounded reads |
| SSRF-safe transport for all HTTP clients | P1 | Apply SSRFSafeTransport to doctor and upgrade commands |
| SVG2 href sanitization | P2 | Strip bare href and single-quoted external URLs in PlantUML SVG output |
| Change | Description |
|---|
| Upgrade KaTeX to 0.16.44 | Update all CDN URLs from 0.16.11 |
| Upgrade chroma to v2.23.1 | Latest syntax highlighter with improved language support |
| Upgrade codecov-action to v6 | Update CI coverage upload action |
| Scope KaTeX in standalone HTML | Target #main-content to avoid processing sidebar text as math |
| Export SSRFSafeTransport | Make SSRF-safe transport reusable via utils.SSRFSafeTransport() |
| Fix | Description |
|---|
| Add figure/figcaption styles to standalone HTML | Center figures and captions with dark mode support via CSS variables |
| Add figure/figcaption base styles to EPUB | Inline fallback styles for images, figures, and captions |
| Add local execution timeout for PlantUML | Prevent indefinite hangs with unbounded context |
Release date: 2026-04-06
Theme: internationalization, rendering, and correctness
v0.7.5 adds i18n support for cover page labels (Chinese, Japanese, Korean), auto-detects figure/table captions for CSS styling, allows Unicode characters in font family names, improves author discovery from git remotes, and fixes a slug collision bug in chapter HTML generation.
| Feature | Priority | Description |
|---|
| i18n cover page labels | P1 | Cover page shows localized Author/Version/Date labels for zh, ja, ko languages |
| Figure/table caption styling | P1 | Paragraphs starting with "Figure N" or "图 N" etc. get class="caption" for centered styling |
| Unicode font family validation | P1 | Font family names with CJK characters (e.g. 思源黑体) are now accepted |
| Git remote owner for author | P2 | Auto-discovery prefers git remote owner over GitHub URLs found in README |
| Fix | Priority | Description |
|---|
| Slug collision in chapter HTML | P1 | Three-way slug collisions (e.g. two chapters slugifying to "intro" plus a natural "intro-2") no longer overwrite files |
| Context leak in image download retry | P1 | Retry path no longer cancels context before response body is read |
| Executable permission after upgrade | P1 | Explicit os.Chmod ensures binary is executable after upgrade write |
| Improvement | Description |
|---|
| Move test-only helper to test file | Remove expandString from production code |
| Caption unit tests | Add table-driven tests for caption pattern matching |
| Slug collision three-way test | Test coverage for N-way slug deduplication |
| Change | Description |
|---|
| Sync Chinese ROADMAP | Add missing v0.6.5-v0.6.9, v0.7.1-v0.7.2 sections to ROADMAP_zh.md |
| Document migrate flags | Add --dry-run and --force flags to CLI reference |
Release date: 2026-04-13
Theme: security hardening, correctness, and documentation sync
v0.7.6 hardens config file loading against TOCTOU races, adds WebSocket pre-checks, prevents git flag injection, fixes site chapter tree slug collisions, and synchronizes architecture documentation with the codebase.
| Feature | Priority | Description |
|---|
| Config file TOCTOU hardening | P1 | Use Open+Fstat+LimitReader to prevent race conditions during config loading |
| WebSocket pre-check before upgrade | P1 | Return HTTP 503 before upgrading when at connection limit |
| Git flag injection prevention | P1 | Prefix directory arguments with ./ to prevent - prefixed dirs from being parsed as flags |
| CSS behavior property sanitization | P2 | Block legacy IE behavior: and -moz-binding: CSS injection vectors |
| Serve network binding warning | P2 | Warn when binding to non-loopback address |
| Fix | Priority | Description |
|---|
| Site chapter tree slug collision | P1 | Use aligned chapterFiles slice for correct mapping when chapters are skipped |
| Temp file leak in PDF fallback | P1 | Clean up temporary file when rename fails |
| GITHUB_TOKEN double-read | P1 | Read token once to prevent mismatch between URL embedding and log redaction |
| Scope KaTeX to chapter content | P2 | Target .chapter-content instead of document.body |
| Plugin cleanup on build failure | P1 | Ensure plugin resources are released even when build fails partway through |
| Improvement | Description |
|---|
| Refactor GitHub source cleanup | Extract cleanupOnError() and validateSubDir() methods to reduce duplication |
| Improve link rewrite normalization | Move extension lowercasing into NormalizePath for consistent map lookups |
| Sync architecture docs | Fix HeadingInfo fields, LocalSource field name, build manifest capitalization, and other doc-code mismatches |
Release date: 2026-04-15
Theme: additional security hardening, correctness fixes, and test improvements
v0.7.7 blocks dangerous URI schemes in cover images, prevents script injection in live-reload, fixes bookmarks option and watermark opacity validation, and strengthens test assertions.
| Feature | Priority | Description |
|---|
| Cover image URI scheme rejection | P1 | Block javascript:, vbscript:, and data: URIs in CSS url() context |
| Live-reload script injection fix | P1 | Escape </ in inline JSON to prevent </script> injection |
| Fix | Priority | Description |
|---|
generate_bookmarks: false ignored | P1 | Always pass document outline option so disabling bookmarks works |
| Watermark opacity out of range | P2 | Clamp values outside [0.0, 1.0] for defense-in-depth |
| Plugin cleanup in serve mode | P2 | Ensure plugin resources are released when serve build finishes |
| Improvement | Description |
|---|
| Strengthen test assertions | Use t.Fatal/t.Skip in CJK tests, add warnRecorder mock, add boundary and whitespace edge cases |
| Sync architecture docs | Fix source module scope and watched file extensions |
Release date: 2026-04-18
Theme: correctness fixes, cross-platform robustness, and documentation sync
v0.7.8 fixes Typst bold+italic conversion, case-insensitive body tag search, URL-encoded image path validation, symlink-aware path traversal checks, and HTML entity handling in search index and meta descriptions.
| Fix | Priority | Description |
|---|
| Case-insensitive body tag search | P2 | Use EqualFold byte scan to avoid index mismatch with multi-byte lowercasing |
| URL-decode image paths in validator | P2 | Decode percent-encoded paths before filesystem validation |
| Typst bold+italic conversion | P2 | ***text*** now correctly produces *_text_* instead of broken output |
| Symlink-aware path validation | P2 | Resolve symlinks on nearest existing ancestor for containment checks |
| HTML entity handling in search | P2 | Unescape entities in plain text so heading lookups and descriptions render correctly |
| Windows path validation test | P1 | Make absolute path test case platform-aware |
| Improvement | Description |
|---|
| Add mermaid bracket diagnostic tests | Comprehensive coverage for bracket matching, nesting, quotes, and comments |
| Sync documentation | Fix changelog links, architecture version, and roadmap ordering |
Release date: 2026-04-19
Theme: cross-platform reliability
v0.7.9 fixes a Windows-specific regression in multilingual build mode where filepath.Rel could fail due to non-absolute root paths.
| Fix | Priority | Description |
|---|
| Windows multilingual switcher injection | P1 | Normalize multilingual root directory to absolute path before generating landing-page and language-switcher links |
| Improvement | Description |
|---|
| Windows multilingual regression coverage | Cover absolute-path normalization and slash-normalized language-switcher links for Windows builds |
Release date: 2026-05-08
Theme: defensive coding, XSS hardening, and bug fixes
v0.7.10 is a security and stability release. It hardens HTML/CSS escaping in the rendered site, prevents symlink and TOCTOU vulnerabilities in the build pipeline, and fixes several user-visible bugs around config priority, slug collisions, and KaTeX rendering.
| Fix | Priority | Description |
|---|
| XSS in search result excerpt | P0 | Encode &, >, " in addition to < before insertion via innerHTML |
| HTML entity escape for headings | P1 | Add single-quote ' encoding for safer attribute contexts |
| CSS escape fallback expansion | P2 | Match CSS.escape() behavior across all CSS special characters |
| Symlink escape prevention | P1 | Validate resolved subdir paths stay within source root |
| TOCTOU race in theme/server reads | P1 | Atomic read paths replace stat-then-read patterns |
| Banner injection size guard | P2 | Reject oversized banner payloads before injection |
| Plugin metadata output limit | P2 | Cap plugin metadata responses to prevent runaway output |
| Go stdlib security update | P1 | Upgrade Dockerfile and toolchain to Go 1.26.2 |
| Fix | Description |
|---|
| Preserve book.json version | Explicit book.json version no longer overridden by README extraction |
| WebSocket nil conn panic | Guard against nil connection in sentinel write |
| Multilingual build root | Resolve build root properly across language variants |
| Slug deduplication collision | Avoid distinct headings collapsing into identical slugs |
| KaTeX multi-chapter rendering | Initialize KaTeX correctly across chapter switches |
| Typst pipeline cleanup | Remove partial PDFs on failure, sanitize embedded newlines |
| PlantUML error chain | Preserve underlying errors with %w wrapping |
| Clipboard / CDN fallback | Graceful degradation when browser APIs or CDN unavailable |
| Improvement | Description |
|---|
| SA5011 lint compliance | Add return-after-t.Fatal and remove redundant nil checks |
| Test assertion strengthening | Replace no-op tests with real assertions across packages |
| Dead code removal | Drop unused CJK fallback, manifest helpers, search variable |
| Dependency updates | fsnotify v1.10.1, chromedp/cdproto refresh |
| Documentation | Document ResolvePath security contract, consolidate EvalSymlinksAncestor |
Release date: 2026-06-17
Theme: correctness fixes, smoother macOS install, dependency refresh
| Fix | Description |
|---|
Deprecated navigator.platform usage | Mac detection now uses navigator.userAgent, so keyboard shortcut badges display correctly in modern browsers |
| SPA search scope and Escape conflict | Search helpers exposed via window globals survive SPA navigation; sidebar Escape handler guarded while the search overlay is open |
| Lightbox focus restore | Stale focus references cleared after restore |
| TOCTOU gaps in file reads | EPUB image loading and other stat-then-read patterns replaced with atomic reads |
| Git clone timeout and credential hang | GIT_TERMINAL_PROMPT=0 plus WaitDelay prevent indefinite blocking; clone timeout configurable |
Root SubDir containment | A subdirectory equal to the source root is no longer rejected as an escape |
| Improvement | Description |
|---|
| Homebrew cask quarantine removal | Post-install hook strips the macOS Gatekeeper quarantine attribute automatically |
| Go 1.26.3 and dependency upgrades | Stdlib security fixes plus chroma, pflag, x/sys, and other refreshes |
| golangci-lint v2.12.2 in CI | GitHub Actions and GitLab CI aligned on the latest linter |
| Expanded English CLI reference | Detailed flag descriptions across command docs |
Release date: 2026-07-05
Theme: full project audit — security, pipeline correctness, safer self-update
| Fix | Priority | Description |
|---|
| Remote plugin execution gated | P0 | Plugins from remote projects run only with the new --allow-plugins flag; local projects are unaffected |
| GITHUB_TOKEN leak in clones | P0 | Token no longer embedded in the clone URL or persisted in the temp clone's git config |
| Security headers on served pages | P1 | Live-reload HTML responses get X-Content-Type-Options, X-Frame-Options, CSP, etc. |
| Plugin trust model documented | P2 | Manuals warn that book.yaml plugins are arbitrary executables |
| Fix | Description |
|---|
| Math preprocessor vs code blocks | $/$$ substitution skips fenced code and inline code, so shell/awk/PHP samples are no longer mangled |
| Typst backend correctness | Valid font: arrays, image path resolution via --root, prose escaping of $ # @ < > and unpaired */_ |
| EPUB image handling | Shared ../images/... assets packaged; non-base64 data URIs warn instead of aborting |
| Live server robustness | Watches newly created directories, serializes rebuilds, WebSocket keepalive, graceful-shutdown panic fix |
serve --branch/--subdir | Both flags now registered on serve for remote previews |
doctor improvements | Typst availability check; --strict exits non-zero on error-level failures |
quickstart target handling | Friendly error for file targets; --force scaffolds into non-empty directories |
| Version reporting | Source builds fall back to runtime/debug.ReadBuildInfo() |
| Improvement | Description |
|---|
Safer upgrade | Respects Homebrew/go install installs (override with --force); fails closed on missing checksums (--skip-checksum opts out) |
| New CLI flags/shorthands | --allow-plugins (build/serve), -o/-f shorthands, --strict (doctor), --force/--skip-checksum (upgrade), --force (quickstart) |
| Linux packages and source archive | Releases add .deb/.rpm/.apk packages and a checksummed source tarball |
| Faster Docker builds | Builder stage cross-compiles via $BUILDPLATFORM without QEMU emulation |
| Documentation accuracy | Removed nonexistent flags from examples, corrected output paths, restored EN/ZH manual parity |
Release date: 2026-07-05
Theme: publication-grade default look and consistent site output
| Change | Description |
|---|
Retuned technical theme | Deep-navy full-bleed default cover, refined navy ink palette, hierarchical book TOC, hairline table borders with tinted headers and zebra striping, framed images, tinted inline-code chips, accent-bar blockquotes; callouts no longer split across PDF pages |
| Centered site reading column | The reading column centers and the right page-TOC rail collapses when empty |
build --format site defaults to _book/ | Consistent with mdpress serve and the deploy examples; --output <dir> writes elsewhere; multi-language builds keep per-language <lang>_site/ layout |
Release date: 2026-07-10
Theme: predictable output paths, a real custom-theme mechanism, per-format rendering quality
| Change | Description |
|---|
Predictable --output semantics | Directory targets receive files and in-place site pages; file-base targets produce <base>.pdf/<base>_site/; default site output builds into a temp dir and atomically swaps _book/ with pruning and a safety check for non-generated targets |
| Remote build outputs | Remote GitHub builds without --output write to the current working directory instead of a temp dir |
| Build result summary | One ✓ Generated <format> → <path> line per format, printed even with --quiet |
| PDF defaults | Centered page-number footer replaces the forced "Built with mdPress" footer; style.header/style.footer honored with {page}/{pages}/{title} tokens; new output.tagged_pdf toggle for smaller untagged PDFs |
| Real custom themes | style.theme: mytheme.yaml loads a YAML theme file; themes/<name>.yaml in the project overrides or defines a theme; themes list/show/preview derive from live palettes |
| Theme retuning and theme-aware covers | Elegant (warm serif, bronze accent) and minimal (quiet monochrome) retuned; default covers follow the theme when no cover is configured |
| Site improvements | Fully relative links (works on GitHub Pages project sites and file://), output.site_url for sitemap.xml, output.edit_base for per-chapter edit links, generated 404.html, dark-mode table/code fixes |
| Standalone HTML | Cover hero section and fixed dark mode |
| EPUB quality | Chapter titles as <h1>, theme-derived reader-friendly stylesheet, math chapters declared scripted remote-resources |
| Serve watcher fix | The infinite rebuild loop after the first edit is fixed by ignoring generated output directories |
| Scaffold cleanup | quickstart/init no longer hardcode a cover background or ship a placeholder cover.svg; a .gitignore is scaffolded; shell completion instructions corrected |
Release date: 2026-07-22
Theme: fix the issues a second full audit confirmed, and add guardrail tests for the patterns that keep producing them
| Change | Description |
|---|
serve --output <dir> is no longer destructive | The rebuild swap deleted the contents of an existing directory; serve now refuses a non-generated target up front, the same check build --format site already had |
| Site root permissions | The atomic swap published a 0700 directory as the site root — a 403 under nginx/httpd; it is now world-readable |
| ePub correctness | Boolean-attribute expansion no longer rewrites prose, chapters sharing a title no longer overwrite each other, cross-chapter .md links are rewritten, and package/NCX/nav references are percent-encoded |
--format typst builds scaffolded projects | book.language was passed verbatim into Typst's lang:, so every generated project failed; it is now reduced to an ISO 639 code |
--format epub -o <newdir>/book.epub | ePub was the only backend that did not create its output directory |
| Typography config is honored | style.font_family / font_size / line_height were read only by the Typst backend; PDF, HTML and site now honor them |
| Site search ranking | Results were truncated to 20 hits before ranking, so a title match could be missing entirely; the reported total was the truncated one |
| Watcher handles deletes and renames | A deleted chapter kept being served until an unrelated edit triggered a rebuild |
| Zero-config language detection | DefaultConfig hardcoded zh-CN, so an English docs folder built a Chinese UI and cover |
--format all drops typst | all failed on any machine without the optional Typst CLI; pass --format typst explicitly |
| Typography defaults moved into the themes | An unset style.* now means "inherit from the theme". Breaking: a book.yaml without language: resolves to en-US unless the content is predominantly CJK |
| Guardrail tests | A cross-format matrix fixture, a style-wiring test driving the real CLI, and a test that resolves every mdpress … invocation in docs/ against the real command tree |
Release date: 2026-07-23
Theme: the class of bug where the build succeeds, the output looks plausible, and the author has nothing to debug with
| Change | Description |
|---|
| Shared image directories |  was dropped from site, standalone HTML and PDF with no diagnostic; containment was checked against the chapter's directory instead of the book root |
Front matter, BOM and stray <h1> | YAML front matter rendered as body text, a UTF-8 BOM stopped the first heading being a heading, and a second <h1> suppressed the page title |
migrate no longer destroys documents | Around an already-fenced block it added a second fence, swallowing the rest of the file — in place, with no backup |
validate as a CI gate | Markdown inside fenced blocks was treated as real references (92 false errors on mdPress's own manual); --strict, anchor checks, orphan and duplicate-chapter checks added |
--config is honored | It was discarded whenever a source directory was also given |
Unknown book.yaml keys | Reported with a "did you mean" suggestion instead of being dropped silently |
| PDF output | output.margin_* reaches @page, the TOC has a heading and real page numbers via a two-pass render, and page-break-inside: avoid no longer leaves near-blank pages |
| ePub output | Documents are parsed before packaging, hierarchy and highlighting are preserved, and a cover image is generated |
| Site weight | Images ship as files rather than base64 in every page: a 3-page book with one screenshot went from 3.5 MB to 1.0 MB |
| Multi-language layout | Breaking: every spelling of --output now resolves to one deployable tree with the switcher at its index.html |
--format site --output ./dist | Breaking: writes to ./dist instead of appending _site when the path does not already exist |
| Ctrl+C stops a build | SIGINT was captured and never acted on, leaving a finished artifact that looked deliberate |
| CDN assets pinned and SRI-checked | A blocked or tampered CDN now shows an explanatory notice and the diagram source instead of a blank gap |
| PlantUML documentation made honest | mdPress does not render it; the manual advertised automatic rendering and doctor told users to install it |
| New commands | config show, cache info/clear, validate --strict, version --json, static/ passthrough, site branding, variables:, section: |
Release date: 2026-07-23
Theme: two defects that v0.8.0's own release run exposed
| Change | Description |
|---|
| A released binary reports its own tag | mdpress version printed 0.8.0+dirty, and 0.7.15+dirty before it: the injected tag was discarded whenever it equalled the compiled-in default — which it does on every correctly prepared release — leaving Go's module version, stamped dirty by goreleaser's own pre-build hooks |
| Windows chapter paths | Zero-config discovery wrote guide\README.md where init and every hand-written book.yaml write guide/README.md |
| Windows test coverage | The CLI test binary was built without a .exe suffix, and an image-containment case named /etc/passwd as absolute — true on Unix, merely rooted on Windows |
Release date: 2026-07-24
Theme: a third full audit — every config key brute-forced against real output, docs mutation-checked against the binary, PDFs/ePubs/sites inspected byte for byte — plus a verification pass over the fixes
| Change | Description |
|---|
mdpress upgrade works on Linux | It downloaded the .apk package instead of the archive and then failed to install it — impossible since v0.7.12; it now selects the archive and refuses any payload that is not a native executable |
build --format site stops deleting <output>.old | The atomic swap used that sibling name as scratch and removed it up front — exactly a user's manual backup; serve deleted it before even the safety check |
| PDF table of contents | Repeated headings across chapters got each other's page numbers; the two-pass render now namespaces anchors like the standalone HTML already did |
build --format typst | Produced no output for any book with a fenced code block or emphasis wrapped across a line — including the project's own manual, which now builds to a 214-page PDF |
| Data-loss fixes | A chapter with lone-CR line endings lost its whole body silently; links with spaces or query strings, and image paths with %20, resolve; an image that cannot be embedded is reported |
| Ctrl+C interrupts a PDF build | It was ignored for the whole 40–90 s render; time-to-exit went from ~55 s (unkillable) to 0.1 s, with no orphaned Chrome |
| Header/footer off the cover | Chrome draws them on every page from the print params where no CSS reaches page one; the cover's running head is now removed while the outline and tagged structure stay intact |
| ePub | Keeps its table of contents under empty parents; a chapter titled "Cover"/"Nav"/"Glossary" no longer overwrites generated files; glossary term links resolve to glossary.xhtml; ids are valid XML |
| Config honored, not guessed | The defaults-as-sentinel defect found five more times (theme page size/margins, a language directory's language, book.json language/version, --config path spelling); loading now tracks which keys the user actually wrote |
| Chrome found on Windows | The search list was Unix-only, so PDF could never work on a stock Windows install |
| Site | Deeply nested chapters are linked; quoted-phrase and CJK search work; dark-mode h5/h6 contrast; shared CSS/JS cut per-page weight from ~110 KB to ~9 KB |
mdpress migrate | Resolves GitBook {{ book.x }} variables instead of shipping literal text, and says so in its report |
| Release safety | make bump VERSION=x.y.z replaces nine hand-edited files; the pipeline now downloads a published artifact and asserts it reports its own tag — the hole that shipped <tag>+dirty twice |
| Docs match the binary | Removed keys that do not exist, corrected stale defaults, and documented every 0.8.0 feature the manual never mentioned, in both languages |
Target release: 2027-Q1
Theme: production readiness and long-term support
| Goal | Description |
|---|
| API stability | Freeze CLI flags and book.yaml structure under semantic versioning |
| Test coverage | Reach at least 90% coverage for core packages |
| Documentation | Complete user manuals, bilingual docs, API docs, and migration guides |
| Performance baselines | Prevent regressions across releases |
| Platform validation | CI coverage across macOS, Linux, and Windows |
| Security review | Continuous dependency scanning and known-vulnerability control |
| Feature | Description |
|---|
| Official theme registry | Community-contributed theme distribution |
| Official plugin registry | Community-contributed plugin distribution |
| Migration tooling | Automated migration from mdBook (GitBook/HonKit migration already available via mdpress migrate) |
The first stable release is intended to become the first LTS version with:
- At least 12 months of bug-fix support
- At least 18 months of security-fix support
- Backward compatibility for config format
- Backward compatibility for CLI flags
These items are post-v1.0.0 and will be prioritized by community demand:
| Feature | Description |
|---|
| GUI editor | Browser-based visual editor |
| Cloud build service | SaaS build service triggered from Git repositories |
| Collaborative editing | Real-time multi-user editing |
| PDF/A output | Archival-compliant PDF support |
| Print-focused output | Bleed, color management, and ICC profile support |
| DOCX output | Word document export |
| Template marketplace | Reusable design and layout presets |
mdPress is open source and welcomes contributions:
- Report bugs in GitHub Issues
- Submit feature requests and note the version you are targeting
- Fork the repository and open pull requests
- Improve docs and translations
- Contribute themes
The roadmap is expected to evolve with community feedback and implementation progress.