Visual Studio Code Extension

DocsForge provides a VS Code extension for writing, previewing, and building documentation without leaving your editor.

Installation

From GitHub Releases (Recommended)

1. Download the latest .vsix file from the GitHub Releases page
2. In VS Code, open Extensions (Ctrl+Shift+X)
3. Click the ... (More Actions) menu → Install from VSIX...
4. Select the downloaded .vsix file

From VSIX (Manual)

# Install via command line
code --install-extension docsforge-vscode-*.vsix

Other VS Code-based editors

The same .vsix works in editors built on VS Code:

• Cursor — cursor --install-extension docsforge-vscode-*.vsix, drag the file into Extensions, or Install from VSIX.
• Windsurf, VSCodium, Kiro, Positron — Extensions → Install from VSIX.
• Antigravity — antigravity --install-extension docsforge-vscode-*.vsix.
• Other forks that accept .vsix files generally work — please report when yours doesn't.

Not supported

Zed, JetBrains IDEs, and Neovim use different extension systems. Studio is
built directly on the VS Code extension API with no language server, so
there is no compatibility layer to port — unlike server-based extensions,
which is how Zensical reaches those editors.

Prerequisites

• VS Code 1.85+
• Python 3.10+ with docsforge installed:
  

  pip install docsforge
  

If docsforge is missing, the extension offers to install it into a project .venv, for your user, or globally — you don't have to set anything up by hand.

Updating

You never have to watch the releases page. The extension updates itself on two channels:

Check for Updates

Run DocsForge: Check for Updates from the command palette (Ctrl+Shift+P), the sidebar Actions view, or the sidebar title bar. One check covers both:

• Engine — the docsforge Python package, compared against PyPI. Updating runs pip install docsforge==<version> in the same interpreter your project already uses (venv, user, or global install), with progress and output in the DocsForge channel. Pre-release engine versions (e.g. 13.0.0b3) now compare correctly against stable releases, so a beta checkout is offered the stable update instead of looking current. An editable install (pip install -e .) is left out of update checks entirely: it tracks source, so update it with git pull + reinstall. Successful checks are cached, so an offline manual check reuses the last-seen versions (labeled cached) instead of failing. On PEP 668 externally-managed interpreters (Debian/Ubuntu system Python) installs and upgrades add --break-system-packages automatically (--user installs keep their flag); when several interpreters have DocsForge installed, every flow asks which one to use instead of guessing.
• Extension — the VSIX itself, compared against GitHub releases. Updating downloads the .vsix to a temp file, installs it, and offers to reload the window.

Automatic checks

About 45 seconds after startup, the extension silently checks in the background and notifies you only when something is newer. Each version nags at most once ("Don't ask again" is per version). Disable it entirely with:

{
  "docsforge.autoCheckUpdates": false
}

Pre-releases

Beta and alpha releases are skipped by default. To track them (recommended while a 13.0.0bN-style beta is current):

{
  "docsforge.includePrereleases": true
}

The sidebar Actions item shows the available versions inline once a check finds them, e.g. Check for Updates — engine 12.5.7 → 13.0.0b3.

Coming from 12.5.7 or older? Those builds predate the updater — install one newer VSIX by hand (see above), and every update after that is one click.

Getting Started

1. Open a DocsForge project

Open a folder containing a docsforge.yml file. The extension activates automatically and prompts:

"DocsForge project detected. Start dev server?"

Select "Yes" to start the dev server immediately, or use the sidebar later.

2. Create a new project

If you don't have a project yet:

1. Click the DocsForge icon in the activity bar (left sidebar)
2. Click Initialize Project
3. Follow the wizard: site name, description, theme color, language, privacy mode, etc.
4. The project is created in your workspace root — editor features activate immediately, no reload needed

Features

Sidebar Actions

The DocsForge sidebar appears in the activity bar and shows contextual actions:

Status Bar

The status bar shows the current server state:

• ▶ DocsForge: stopped — Click to start the server
• ▶ DocsForge: starting... — Server is starting up
• ▶ DocsForge: http://localhost:8000 — Server is running. Click to open preview

Dev Server

The extension runs docsforge serve --no-open in the background:

• Output streams to the DocsForge output channel (Ctrl+Shift+U → select "DocsForge")
• A progress notification shows "Starting DocsForge server..." until the URL is detected
• When the server is ready, the URL appears in the status bar
• VS Code's built-in browser handles navigation and hot-reload

Multiple projects (multi-root)

Each open folder gets its own server, build, and Python environment. Serve/Build act on the active file's project (a picker appears when several projects are open with no file context), the status bar names the folder when more than one is open, and Open Built Page uses the current document's own project server.

Preview

Click Open Preview to see your site in VS Code's Simple Browser. This is VS Code's Electron-based browser — it supports all feature navigation, search, and page transitions.

Build

Click Build to run docsforge build. Output streams to the DocsForge channel. A notification shows the result. Diagnostics refresh automatically when the build finishes.

Editor intelligence

No language server needed — the extension reads your project directly:

• Diagnostics — broken links, missing anchors, footnote problems, and missing/orphan translations surface as squiggles, sourced from the build's validation cache and refreshed after every build (or on demand via Refresh Diagnostics)
• Link navigation — go-to-definition and hover on Markdown links jump to the target document and anchor; path completions inside (...) suggest project files
• Anchor completions — after # inside a link, headings of the target document (same file for ](#…)) complete as slugs, backed by a cached heading index in .docsforge/studio/
• Snippet completions — inside --8<-- "…" includes, sibling files and docs-tree paths complete (paths resolve against the source file's directory first)
• Frontmatter completions — known keys (title, description, icon, tags, hide, search, template, …) plus hide:/search: values on Ctrl+Space; custom keys stay legal and are never flagged
• Rename — Rename Document moves a file (plus its translations) and rewrites every link to it in one undoable step; Rename Anchor does the same for headings, including same-page [text](#anchor) links. Renaming a folder in the Explorer updates links too
• Quick fixes — the lightbulb on a broken link offers to fix it; when several same-named files match you pick the target, and Fix All covers only unambiguous links
• Formatting — Format Document tidies trailing whitespace and blank-line runs (also available on save via editor.formatOnSave)

Configuration

Settings

Example: Configuring Python Path

If you use a virtual environment or a non-default Python:

{
  "docsforge.pythonPath": "/home/user/.venv/bin/python"
}

Or via .vscode/settings.json in your project:

{
  "docsforge.pythonPath": ".venv/bin/python"
}

Workflows

Edit → Preview Loop

1. Start Server from the sidebar
2. Click Open Preview when it's ready
3. Edit your Markdown files
4. The preview auto-reloads on save
5. Stop Server when done

Build → Deploy

1. Build from the sidebar
2. Check the output for any errors
3. The built site is in site/ — deploy anywhere

Initialize → Develop → Deploy

1. Initialize Project — creates the project structure
2. Start Server — preview and iterate
3. Build — production build
4. Deploy site/ to your hosting platform

Stay current

1. Accept the update notification, or run Check for Updates
2. Update the engine, the extension, or both
3. Reload when prompted — that's the whole release process

Troubleshooting

Commands

All available commands (accessible via Ctrl+Shift+P):

Next Steps

• Usage Guide — Day-to-day DocsForge usage
• Deployment Guide — Deploy your site after building
• Features — All core features