
Ascribe for VS Code
Write Ascribe documentation with the checks, completion, navigation, and preview a programming language gets. Ascribe is Markdown with directives for the structure documentation needs: callouts, procedures, alternatives by platform or product, availability, and reusable content.
The extension activates in a workspace that contains an ascribe.toml. A workspace can hold several projects, each with its own language server: see workspaces with several projects.
Features
- Diagnostics as you type, across the whole project, the same ones
ascribe check reports in CI. Many come with a quick fix, and Apply the safe fixes in this page applies the safe ones together, on request or on save.
- Completion for directives, attributes and their values, phrases, availability, include paths, and links, which you search by page and heading title rather than by path.
- Hover for links and includes (the target's title and first paragraph), phrases (their values), and availability (what it means on the published site).
- Navigation: go to definition, Find All References for pages, headings, phrases, and the rest of the content model, clickable links, a CodeLens on each include, one in a code file a page shows that says which pages show it, and hints that show the title an empty-text link will get.
- Search Pages as Readers See Them: find words as readers read the pages, through phrases and fragments, in the build you're looking at or every build, unsaved text included, and open the line that wrote them.
- Refactoring: renaming or moving a file updates the links and includes that point to it; renaming a heading's
@id, a phrase, or a dimension value updates its uses.
- Formatting into canonical form, on request or on save, and highlighting of directives, phrases, and title lines.
- A live page preview that renders the page as the published site does, as you type, for any build, and a site preview that opens it on the site's dev server.
- Actions that write Ascribe for you: wrap a paragraph in a note, turn a list into steps, link to a page by its title, insert content that varies, mark where a section is available, or make the selected text a phrase. The actions bar (
Ctrl+K A, Cmd+K A on macOS) lists the ones that apply where the cursor is; each asks what it needs, so you never type the syntax.
- The Ascribe sidebar: the project, with its server, the build you're looking at, Project Settings, and what it's made of, and its health, counted only while each count is current: its problems in every build, stale examples, overdue rechecks, orphans, unused entries, and agent files out of date, with every safe fix and every page formatted as one edit, left unsaved, Build, Sync Agent Files, and Observe Examples as tasks in the terminal, and Start Review and Prompt Agent beside them; the page you're on with its title, its addresses, whether it's published, listed, due, or over size, and what links to it, with a badge counting what needs doing; the project's pages and the ones nothing links to; and its content model with how much each entry is used. In a workspace with several projects, Switch Project, in the Project view's title bar, shows another.
- Project Settings: a tab of the project's own settings, in
ascribe.toml, each with its value, its default, what it does, and the line that sets it, and every check whose level the project can set, found by a search over every word of their descriptions. Change a value there, add one the file leaves out, or reset one to its default, and ascribe.toml changes, unsaved, with its comments kept. Content types, builds, and the rest are cards that open the file at their table. Opened from ascribe.toml's title bar, the Project view, or the Command Palette.
- The build you're looking at, in the status bar: switch it, and the preview renders it and the build lens dims what it leaves out of the page.
- Review: the preview marks what changed against a git revision, a Review view in the sidebar lists the pages a change touches with their problems and opens the source changes in one diff, and the preview shows the pull request's review comments beside the blocks they're about, where you can reply, resolve, comment, and submit your review. Reviewing a pull request walks through it.
- Agents: an agent in VS Code gets Ascribe's MCP server and its skill with nothing to set up, and tools that see what's in the editor before it's saved and the review that's open. Prompt agent builds a prompt about a problem or a review comment for your agent. See Agents in VS Code.
After you install it, the Get Started with Ascribe walkthrough goes through the first steps. It's under Help → Welcome whenever you want it again.
The ascribe binary
The extension includes ascribe for your platform, so it works immediately. When a project installs its own (npm install --save-dev @ascribed/cli), the extension uses that one for it instead, so the editor matches the version the project pins for CI. The ascribe.path setting overrides both.
Settings and commands
The extension's Feature Contributions tab lists them, and Editing with Ascribe describes each one.
Learn more
Other Markdown formatters that reflow paragraphs don't know that Ascribe's directive and title lines start new blocks; exclude Ascribe files from them.
| |