Ziraflow for VS Code
Preview any markdown or DocLang file and export it to Word or PDF, locally and
without an account. Nothing leaves your machine: the work is done by the
doclang engine bundled with the extension.
Features (no account)
- Live preview beside the editor (
Ziraflow: Open Preview to the Side, or
the preview icon in the editor title bar). It refreshes as you type, from the
unsaved buffer.
- Page: A4 or Letter sheets (doclang theme
page-view). Default.
- Web: reading column with a table of contents (theme
professional).
- The mode is remembered per workspace.
- Charts,
$$ math and mermaid render from pinned CDN files (exact URL
plus SRI hash, per doclang version in src/core/cdnAllowlist.ts). Maps
are not loaded in the preview (tile servers); a placeholder shows instead.
- View as Word generates the real
.docx into a temp folder and opens it
in your default app, because HTML never paginates exactly like Word.
- Export to Word / Export to PDF: writes
<name>.docx or <name>.pdf next
to the source and asks before overwriting. It builds what is in the editor,
unsaved changes included. Local images inside the file's folder are
embedded; an image in an @included file resolves from that file's folder.
Charts and math render without network (with Chromium, see below). Remote
(http(s)) images are not downloaded: Word and PDF show a marker in
their place. If images are left out, the notification lists them and why.
- Export selection to one Word document: select several
.md files (in
selection order) or a folder (its files in name order) in the Explorer.
Each file's images resolve from its own folder, confined to the
selection's common folder.
- Problems panel: doclang lint findings show up as diagnostics on the
source file: always for
.doclang, and for a .md once you preview,
export or publish it (or for every .md with ziraflow.lintMarkdown).
At most two lint processes run at once.
- Local MCP server: registers
doclang mcp as Ziraflow (local), so
Copilot or another chat in VS Code can lint and preview documents.
Commands appear in the editor context menu, the Explorer context menu (single
file, multi-select, folder), the editor title bar and the Command Palette, only
for markdown and DocLang files.
Chromium
PDF export, and mermaid diagrams, charts, math and SVG images inside Word,
need Chrome, Edge or Chromium. doclang renders them on this machine without
network; Chromium only draws them.
The extension looks for an installed browser and for the build that
doclang --install-chromium downloads. If none is found it offers to install
the Chromium build pinned by doclang (checksum verified, about 150 MB; Linux
x64, macOS and Windows x64). Until then PDF is disabled with a message. For
Word, doclang itself reports what it could not draw without Chromium; only
then does the extension ask, and you can keep the Word file with markers.
Settings
| Setting |
Default |
Description |
ziraflow.doclangPath |
empty |
Path to doclang, 2.49.1 or later (every build passes --base-dir, new in 2.49.0, and image paths follow CommonMark from 2.49.1; an older binary is refused). Empty: bundled binary, then doclang on PATH. |
ziraflow.chromiumPath |
empty |
Chrome/Edge/Chromium for PDF and diagrams. Empty: auto-detect. |
ziraflow.preview.debounceMs |
400 |
Quiet time after typing before the preview refreshes. |
ziraflow.lint.enabled |
true |
Publish lint findings to Problems. |
ziraflow.lintMarkdown |
false |
Lint every .md automatically. Off: .doclang files always, a .md only after a Ziraflow command ran on it. |
ziraflow.mcp.local.enabled |
true |
Register the local MCP server. |
ziraflow.instance |
production |
production (https://nala.ziraflow.com), dev (https://dev.nala.ziraflow.com) or custom. |
ziraflow.customApiUrl |
empty |
API URL when ziraflow.instance is custom. https, or http on 127.0.0.1/localhost only. |
ziraflow.writeIdToFrontMatter |
false |
Also store the document id in the front matter after the first publish. |
ziraflow.mcp.remote.enabled |
true |
Register the remote Ziraflow MCP server while signed in. |
With a Ziraflow account
Sign in with Ziraflow: Sign In (or from the Accounts menu). The browser
opens the Ziraflow sign-in and consent page; the extension listens on
127.0.0.1 for the answer (5 minute limit) and keeps the tokens in VS Code's
secret storage. Everything below talks to your account through the remote
Ziraflow MCP server only.
- Publish to Ziraflow (editor title bar, editor and Explorer context menus,
Command Palette). The first publish creates the document; later publishes
send a new version.
- Publishes the saved file. With unsaved changes it asks first.
@include files are inlined before sending, the way doclang expands
them: only files inside the published file's folder (doclang refuses a
.. that leaves it, or a symlink that resolves outside it), no cycles,
at most 16 levels. An @include inside a code block stays as written,
as doclang 2.56.0 keeps it; the extension asks doclang which lines those
are, so publishing a file with @include needs doclang (the bundled one,
or a ziraflow.doclangPath of 2.49.1 or later). Images of included files
are rewritten relative to the published file, as doclang does when it
builds. A file that leaves a block open (a code fence, $$, a
:::code-group) stops the publish on its @include: doclang 2.57.0
closes it where the file ends (INCLUDE002), and the inlined text would
not, unless only blank lines follow it.
- Local images go with the document: PNG, JPEG, GIF or WebP, inside the
workspace folder, at most 20 images, 2 MB each and 6 MB in total.
Remote images (
https://…) and SVG are not accepted: the publish stops
and Problems shows each one on its line.
- If someone published another version in Ziraflow since your last publish,
you choose: Replace with My Version, Open in Ziraflow, or cancel.
- DocLang errors reported by Ziraflow land in Problems on the right line.
- The link between a file and its document is kept per workspace. With
ziraflow.writeIdToFrontMatter it is also written into the front matter
(ziraflow: { id }), so it survives a fresh clone; publishing such a file
from a new clone asks before adding a version.
- Open in Ziraflow.
- Copy Share Link: copies the current link, or creates one with an optional
expiry and password (those need a plan with private links).
Revoke Share Link turns it off.
- Status bar: the account, and for the active file whether it is not
published, published (vN) or modified since the last publish.
- Remote MCP server: while you are signed in, the remote server is
registered as Ziraflow next to Ziraflow (local). VS Code connects to
it with its own OAuth sign-in, so the first time chat uses it VS Code asks for
consent again; that grant is separate from the extension's.
Coming later: organization Word templates.
Requirements
VS Code 1.101 or later (MCP server registration API).
Account features need a Ziraflow server whose OAuth server lets the same
client reuse a just-rotated refresh token for 60 s (multi-use grace, PR #806).
Several VS Code windows refresh the session independently; on an older
server, two windows refreshing at once revoke the connection.
Development
pnpm install # from the repo root (pnpm workspace)
pnpm run lint # eslint + tsc --noEmit
pnpm run build # esbuild -> dist/extension.js
pnpm test # vitest unit tests (pure modules)
pnpm run test:account-e2e http://localhost:3001 /tmp/zf-e2e # sign-in + publish against a local backend (MCP_ENABLED, DEV_SKIP_AUTH)
pnpm run smoke --doclang /path/to/doclang --source ../../docs/architecture/backend.md --chromium /usr/bin/microsoft-edge
node scripts/fetch-doclang.mjs linux-x64 [--pinned] # bundle the pinned doclang (2.59.0), sha256-checked
pnpm run package:linux-x64 # fetch + vsce package --target linux-x64
pnpm run check-vsix ziraflow-linux-x64-0.1.0.vsix linux-x64 # expected files only, pinned doclang, exec bit
src/core/ holds the modules with no vscode dependency (binary resolution,
CLI arguments, front matter helpers, include manifests, lint report
parsing, process handling); src/vscode/ holds the editor integration.
Account features live in src/core/account/ and src/core/publish/ (no
vscode: OAuth, token refresh, MCP client, include flattening, image
collection, publish flow) and src/vscode/account/ (authentication provider,
commands, status bar, remote MCP registration), registered as a second command
module in src/extension.ts.
License
Proprietary, see LICENSE.md. The bundled doclang binary is
Apache-2.0 (ziradocs/toolchain); its LICENSE and NOTICE ship next to it.
| |