Skip to content

0.2.0 - 2026-11-05

Latest

Choose a tag to compare

@github-actions github-actions released this 05 Nov 14:11
8bb82f3

Release Notes

New Features

  • Markdown includes — Reuse Markdown across pages with ::include[path.md], including nested includes, search and publishing support. See Includes.
  • Project images and files — Show project images and link to documents in rw serve and embedded viewers. See Images and files.
  • Diagram files — Render diagram source files with Markdown image syntax, such as ![Flow](flow.puml). See Diagrams from files.

Added

  • ::include[path.md] embeds reusable Markdown, including nested includes, across serving, search, Confluence and S3 publication. See Includes.
  • Project images and linked PDFs, Office documents, CSVs and ZIPs work in rw serve and embedded viewers. Hosts serve them through @rwdocs/core's getFile() and copy its response headers. See Images and files and Embedding.
  • Markdown images can render diagram files. Kroki support adds D2, Pikchr, DBML, BPMN, Excalidraw, GoAT and UMLet; SVG-only formats cannot be exported to Confluence. See Diagrams.
  • Diagram fences accept quoted attributes with spaces and alt text for screen readers and Confluence attachments. See Attributes.
  • Page-local JSON-compatible attrs survive S3 publication and appear as meta.attrs in @rwdocs/core's renderPage() responses. They never inherit or change rendering. See Page Metadata.
  • Tabs and other ::: directives accept compact layouts without surrounding blank lines. Unknown or malformed directives warn. See Tabs.
  • rw comment and rw confluence render accept --project-dir; comment commands also accept --config. See Configuration.
  • Core renderPage(), renderSearchDocument() and getPageMarkdown() accept page paths with a leading slash, including / for the homepage.

Changed

  • Breaking (pre-1.0): folder README pages move from /guides/README to /guides: update external links. Beside index.md, README is omitted; rename it to keep a separate page. Existing comments do not move. See README pages.
  • Breaking (pre-1.0): Markdown files and folders starting with _ no longer have pages, navigation or search entries. Rename them to keep publishing them as pages; they can still supply included text. See Navigation ordering.
  • Breaking (pre-1.0): frontmatter must start the file, before blank lines or HTML comments. Move preceding content below it. See Page Metadata.
  • Breaking (pre-1.0): container directive labels require brackets: use :::tab[macOS], not :::tab macOS, which now stays literal text. See Tabs.
  • Breaking (pre-1.0): docs.source_dir and configured PlantUML include_dirs must stay inside the project, including symlink targets. If moving rw.toml to a shared parent, update both relative paths. Explicit Confluence -I directories remain supported. See Configuration and Diagrams.
  • Breaking (pre-1.0): project images, file links, diagram files and Markdown/PlantUML includes use case-sensitive paths on every OS. Match the spelling on disk; rw warns about case collisions.
  • Breaking (pre-1.0): PlantUML !include accepts only PlantUML extensions. Rename other extensions to keep including those files. See PlantUML Includes.
  • Breaking (pre-1.0): Markdown links now resolve from their source file, including a project-root README. Update links that relied on resolving from the docs directory instead. See README pages.
  • Breaking (pre-1.0): wikilink targets use literal filenames: write [[::my page]], not [[::my%20page]]. A kindless section reference now matches any kind; specify the kind when names are ambiguous. See Wikilinks.
  • Breaking (pre-1.0): mountRw() replaces initialPath with basePath and encoded location; drop embedded. Pass every host location change to navigateTo(), which no longer invokes onNavigate; viewer-initiated page navigation still does. See Migration.
  • Breaking (pre-1.0): mountRw() enables comments only with an explicit comments client. For rw-compatible routes, pass createCommentApiClient(apiBaseUrl, fetchFn); the viewer no longer fetches /config. See Enable comments.
  • Upgrade @rwdocs/core and @rwdocs/viewer together: the viewer now reads meta.documentId. Comments stored under truncated #-path keys do not appear on their corrected pages; RW does not migrate them. See Comment migration.
  • Upgrade S3-backed @rwdocs/core readers before publishing with this release. Older readers cannot fully interpret README pages, included Markdown or page attrs. No render-cache clearing is needed. See Embedding.
  • Breaking (pre-1.0): Confluence bundles now contain local images as well as diagram PNGs. Upload every attachment with its actual MIME type, not a hard-coded image/png. See Bundle format.
  • Breaking (pre-1.0): createSite({ projectDir }) no longer reads RW_DIAGRAMS_KROKI_URL. Pass diagrams: { krokiUrl } or configure diagrams.kroki_url in rw.toml.
  • Breaking (pre-1.0): createSite()'s mtimeSource is typed as "filesystem" | "git"; other values now throw for S3 sites too.
  • Breaking (pre-1.0): commands fail with exit 3 when the project has neither a docs directory nor a README homepage. Run from the project root or pass --project-dir; Confluence can still render standalone files with an explicit root.
  • Breaking (pre-1.0): missing --project-dir or --config paths and missing comments/documents exit 4. Exit 2 is reserved for argument errors. See Exit codes.
  • rw backstage publish --strict now catches all page and scan warnings, including broken links, duplicate section refs, case collisions and unavailable images. rw confluence render --strict also fails on unsupported file links, failed diagrams and attachment writes.
  • CLI warnings now go to stderr by default, including render warnings on cached pages. RUST_LOG overrides --verbose; use RUST_LOG=error to suppress logged warnings. Machine-readable stdout stays free of logs.
  • S3 publication skips unchanged pages and images when the bucket grants s3:ListBucket.
  • Repeated git-based page renders no longer slow down as commit history grows. In a 108 KB page test, Confluence rerenders with inline comments dropped from about 4 seconds to under 0.1 seconds.
  • A real PlantUML include file now takes precedence over a C4 metadata include of the same name. Rename or remove the file to use metadata. See Diagram Includes.
  • Embedded viewer controls now honor dark mode.
  • Building from source requires Rust 1.99.1. The viewer's npm Node requirement is ^22.22.2 || ^24.15.0 || >=26.0.0.

Removed

  • Breaking (pre-1.0): rw serve --cache <BOOL> and --live-reload <BOOL> are gone. Use --no-cache or --no-live-reload; both remain enabled by default.
  • Breaking (pre-1.0): [metadata] name is ignored. Rename custom sidecars to meta.yaml or <name>.meta.yaml. See Page Metadata.
  • Breaking (pre-1.0): rw serve --embedded is replaced by the always-available preview at /_embedded/.
  • Breaking (pre-1.0): GET /_api/comments/{id} returns 405. Use GET /_api/comments?documentId=… or rw comment show <id>.

Fixed

  • Page links, navigation and breadcrumbs handle non-ASCII names, reserved URL characters, queries, relative paths and folder index pages correctly. Dotted page URLs work on direct loads; protocol-relative links remain external.
  • Page titles consistently use the opening H1's visible text, not a later heading. Blank metadata falls back correctly, frontmatter supports BOM/CRLF files, and later --- blocks remain content. See Title resolution.
  • Live reload picks up metadata edits, directory moves/deletions, README replacement saves, and the first edit after a server restart. Changes to PlantUML includes invalidate affected cached pages.
  • Live reload preserves the reader's position and expanded sidebar sections, refreshes links when pages change, and resynchronizes after reconnecting.
  • Comment creation rejects nonexistent pages, empty quotes and replies to replies. Emoji selections and quotes in sections with reserved characters anchor correctly; other open viewers receive changes even if the submitting tab disconnects.
  • Embedded navigation preserves host router state, respects host scrolling and leaves host shortcuts and Escape presses alone. The table of contents stays reachable beside comments; tabs show keyboard focus and navigation expand buttons announce page names.
  • Viewer requests aborted by a custom host fetch show an error instead of loading forever. Destroyed viewers no longer finish initialization or leave their dark-mode class behind.
  • rw serve stays responsive while a browser launcher or Kroki request is slow, binds unbracketed IPv6 addresses, and refreshes comments without requiring CLI loopback access.
  • rw comment list prints readable columns and complete IDs. Read-only comment commands no longer create a database; writes protect .rw/ with a gitignore.
  • PlantUML includes resolve relative to the including file, support diagram/subpart selectors and include-once semantics, and expand without corrupting surrounding text. See PlantUML Includes.
  • Directives preserve literal text, honor escapes and quoted attributes, and respect list/blockquote boundaries. Colon-prefixed prose stays text; a tight-list edge case no longer panics.
  • Confluence rerenders preserve comments and formatting, and avoid malformed XHTML from code blocks or HTML void elements.
  • Previously invisible blockdiag-family diagrams display at natural size, and nested hand-authored diagrams zoom correctly. C4 titles can contain quotes; diagram warnings are numbered from 1 in page order.
  • Interrupted cache writes no longer leave cached pages or diagrams broken. S3-backed sites recover from invalid manifest metadata and no longer reuse another process's stale page tree.
  • Git timestamps work for relative project paths and CRLF checkouts; staged edits use filesystem times.
  • S3 bucket prefixes ignore surrounding slashes. Republish bundles previously written with such slashes; old objects are not deleted.
  • CLI and core errors name failing paths and underlying causes without duplicating them.

Security

  • rw serve rejects unknown request hostnames to prevent DNS rebinding. Add legitimate custom names with --allowed-host or server.allowed_hosts. See Allowed hosts.
  • Project-root README symlinks cannot expose files outside the project, and development asset reads reject path traversal.
  • PlantUML includes cannot escape allowed include directories through absolute paths, .. or symlinks, preventing unrelated files from reaching Kroki or S3 bundles.
  • Repeated wikilinks with empty labels no longer expand content exponentially and exhaust memory.

Install rw 0.2.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/rwdocs/rw/releases/download/v0.2.0/rw-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/rwdocs/rw/releases/download/v0.2.0/rw-installer.ps1 | iex"

Install prebuilt binaries via Homebrew

brew install rwdocs/tap/rw

Download rw 0.2.0

File Platform Checksum
rw-aarch64-apple-darwin.tar.xz Apple Silicon macOS checksum
rw-x86_64-apple-darwin.tar.xz Intel macOS checksum
rw-x86_64-pc-windows-msvc.zip x64 Windows checksum
rw-aarch64-unknown-linux-gnu.tar.xz ARM64 Linux checksum
rw-x86_64-unknown-linux-gnu.tar.xz x64 Linux checksum
rw-x86_64-unknown-linux-musl.tar.xz x64 MUSL Linux checksum