The language server

ascribe lsp, for an editor other than VS Code: setups for Neovim and Helix, the project a server serves, what it asks of the editor, and the requests of its own, with their parameters.

For AI agents: the documentation index is at llms.txt, and this page is available as Markdown.

Every feature of the VS Code extension that isn’t drawn on the screen comes from the language server, ascribe lsp, which runs the same checks as ascribe check. Any editor with a Language Server Protocol client can run it from a project installed with @ascribed/cli, and gets the problems, completion, hover, navigation, renaming, formatting, and fixes the extension has. The preview, the sidebar, and review are drawn by the extension, from the requests of the server’s own below.

ascribe lsp

Runs the language server, speaking the Language Server Protocol over standard input and output. An editor starts it; you don’t run it yourself. It takes no options of its own, and refuses --config (exit code 2): its project is the nearest ascribe.toml at or above the workspace folder the editor gives it, never one below, and ascribe.toml’s [editor] build says which build’s page-level problems to report. Its logs go to standard error; the project it uses is sent to the editor as a log message when it starts. The options every command accepts are in the command reference.

Set up your editor

An editor needs three things to run the server: the command, npx ascribe lsp; the files to send it, Markdown pages and ascribe.toml; and the project’s root, the folder that holds ascribe.toml. npx runs the @ascribed/cli a project installs (In a project, with npm), looking for it from the folder the editor starts the server in and then in each parent. When the editor starts it somewhere else, or you put ascribe on your path instead (On your path, without Node), write the binary’s path, or ascribe, in place of npx and ascribe.

The server reads no settings of the editor’s: it ignores initializationOptions, never asks for workspace/configuration, and doesn’t follow workspace/didChangeConfiguration. What it checks and which build it reports come from ascribe.toml, its [editor] build above all, so every editor gets the same problems. The VS Code extension’s settings are the extension’s own, and none of them reaches the server.

Neovim

Neovim 0.11 and later configure a server with vim.lsp.config. In your init.lua:

vim.lsp.config("ascribe", {
  cmd = { "npx", "ascribe", "lsp" },
  filetypes = { "markdown", "toml" },
  root_markers = { "ascribe.toml" },
  workspace_required = true,
})
vim.lsp.enable("ascribe")

root_markers starts one server for each project, at the nearest ascribe.toml above the file. workspace_required, which Neovim reads from 0.11.1, starts none for a file outside every project. Without it, or in 0.11.0, such a file gets a server of its own with no project, which reports nothing.

Helix

Helix configures servers in languages.toml, in its configuration folder or in a project’s .helix/ folder:

[language-server.ascribe]
command = "npx"
args = ["ascribe", "lsp"]

[[language]]
name = "markdown"
roots = ["ascribe.toml"]
language-servers = ["marksman", "ascribe"]

[[language]]
name = "toml"
roots = ["ascribe.toml"]
language-servers = ["taplo", "ascribe"]

A language’s language-servers replaces the list Helix has for it, so name the other servers you use beside ascribe, as these keep marksman and taplo. roots makes the nearest ascribe.toml above the file the server’s root. hx --health markdown says whether Helix finds the command.

Zed

Zed runs a language server only from an extension: its settings can change how an extension’s server starts, but can’t add a server. Ascribe has no Zed extension, so there’s no setup to copy for Zed yet.

The project a server serves

A server serves one project, the one ascribe lsp finds, so a server started at the root of a repository whose projects are all in subfolders has no project. For a workspace with several projects, start one ascribe lsp per project, rooted at the folder that holds its ascribe.toml, and give each file to the server of the nearest ascribe.toml above it. Marking a project’s root by its ascribe.toml does both, as each setup below does. The VS Code extension does the same, one server for each project in the workspace: see Workspaces with several projects.

When it starts, the server sends a window/logMessage at Info with its version and the project it uses: ascribe-lsp <version>: using the project at <path>, or, when it finds none, ascribe-lsp <version>: no ascribe.toml at or above <folder>. A server with no project reports nothing. If an ascribe.toml is then created in the workspace folder itself, the server loads it, when the editor supports watching files for the server.

When one project is nested in another’s content root, the outer project’s server leaves the nested project’s files alone, open or not, so each file gets its problems from one server only. A nested project’s ascribe.toml created or deleted while the server runs changes which files it checks, when the editor supports watching files for the server.

What it asks of the editor

The lens in a code file a page shows and the action that applies a page’s safe fixes come from the server, so any editor that asks gets them. The server asks for lenses in its sources’ files by registering them for those files (client/registerCapability for textDocument/codeLens), when the editor supports registering lenses; one that doesn’t gets the lenses on @include in the pages it sends.

The lens on an @include, and on one memo, runs ascribe.openFile, the server’s own command, which needs nothing of the editor: the server answers it by asking the editor to show the file (window/showDocument). Four commands are the editor’s to run:

Command Carried by Its arguments
ascribe.showReferences The lens in a code file a page shows A file, a position in it, and the places, as VS Code’s editor.action.showReferences takes them
ascribe.showMemos A lens that counts several memos The memos, to pick one from
ascribe.selectRange The quick fix that writes a term’s definition A file, and the range to select in it after the edit; an editor that doesn’t run it still gets the edit
ascribe.copyCommand The quick fix Copy the command on example-stale and example-unobserved The line of shell that observes the example’s source again, to put on the clipboard; an editor that doesn’t register it gets a quick fix that does nothing

The action that applies a page’s safe fixes has the kind source.fixAll.ascribe, which editor.codeActionsOnSave can name (Apply the safe fixes).

Ascribe’s own requests

Beside the standard requests, the server answers requests of its own, which the VS Code extension draws its views from. None is advertised as a capability: a client that wants one sends it. Each answers from the text the editor has, unsaved edits included, and each result’s shape is a JSON Schema in the schemas/ folder at the release’s tag, generated from the code that answers it. Their parameters are below.

Request What it answers Its schema
ascribe/preview A page rendered as the published site renders it, for a build, with source anchors on its blocks: the page preview lsp-preview.schema.json
ascribe/review/setBase Sets the git revision to compare the project with, or clears it lsp-set-base.schema.json
ascribe/review/changes The pages of a build that changed against the base: the Review view lsp-changes.schema.json
ascribe/review/baseFile A file’s text at the base, for a diff of the source lsp-base-file.schema.json
ascribe/context What’s at a position or a selection of a page, so a client knows which actions apply there lsp-context.schema.json
ascribe/targets What an action can point at or use in the project: its pages, headings, fragments, images, snippets, phrases, and the rest lsp-targets.schema.json
ascribe/edit The edit one action makes to a page lsp-edit.schema.json
ascribe/inventory What the project has and how much each part is used: the Pages and Content model views lsp-inventory.schema.json
ascribe/settings Every setting of ascribe.toml with its value, its default, and its line: Project Settings lsp-settings.schema.json
ascribe/page What’s known about a page, and what links to and includes the heading at a position: the This page view lsp-page.schema.json
ascribe/projectEdit One edit to every page of the project, its safe fixes or its formatting: Edits to the whole project lsp-project-edit.schema.json
ascribe/buildView What a build leaves out of a page: the build lens lsp-build-view.schema.json
ascribe/search Where the pages say something, as readers read them: Search lsp-search.schema.json
ascribe/agentPrompt A prompt for an agent about one problem, a file’s, or the project’s: Prompt your agent lsp-agent-prompt.schema.json

The server also sends one notification of its own, ascribe/preview/changed, with { "pages": [uri, …] }, when files changed on disk change how pages read: a page or a fragment it includes, or a file a @snippet in either shows. A client with a preview of one asks for it again; one that doesn’t preview can ignore it.

Lost addresses

In a project that keeps its addresses, the server sends a second notification, ascribe/addresses, with what comparing the addresses with the base’s found: ascribe.addresses’ URI, the base, the count of pages lost, and the problems at the file, as ascribe check reports them (lsp-addresses.schema.json). It compares after the project loads, a save, a change on disk, or an edit to ascribe.addresses, never as a page is typed. A client shows the problems as the project’s, not as a page’s diagnostics. ascribe/page’s about.alsoAnswersAt lists the old addresses that lead to the page.

The requests’ parameters

Each request names a document by its URI, as textDocument, and the server answers for that document’s project. Positions and ranges are in the position encoding the editor and the server agreed on at initialize. A request whose parameters don’t parse gets the error InvalidParams; every other problem is in the result, as its schema says.

ascribe/preview

{
  "textDocument": { "uri": "file:///…/docs/install.md" },
  "build": "cloud",
  "review": true
}

build names the build to render the page for, and without it the editor’s build, [editor] build. With review true and a base set, the result says what changed on the page against the base too.

ascribe/review/setBase

{ "base": "main" }

base is a branch, a tag, or a commit, compared from its merge base with HEAD, as ascribe diff compares. Without base, the default branch: the first of origin/HEAD, origin/main, origin/master, main, and master. null stops comparing and frees the base. Nothing runs git until a base is set.

ascribe/review/changes

{ "build": "cloud" }

build is optional, the editor’s build without it. The pages are compared with the base that ascribe/review/setBase set.

ascribe/review/baseFile

{ "textDocument": { "uri": "file:///…/docs/install.md" } }

The document is ascribe.toml or a source file in the content root.

ascribe/context

{
  "textDocument": { "uri": "file:///…/docs/install.md" },
  "range": { "start": { "line": 20, "character": 5 }, "end": { "line": 20, "character": 5 } }
}

An empty range is the cursor; any other is a selection.

ascribe/targets

{
  "textDocument": { "uri": "file:///…/docs/guide/install.md" },
  "kinds": ["pages", "headings", "fragments", "images", "snippets", "phrases",
            "notes", "dimensions", "widgets", "features", "builds", "occurrences", "types"],
  "range": { "start": { "line": 8, "character": 4 }, "end": { "line": 8, "character": 15 } },
  "folder": "file:///…/docs/guide"
}

kinds names the lists to answer, and the result has those and no others. range, the cursor or a selection, is optional, and only occurrences reads it: the other places in the project’s prose with the words it selects. folder, a folder in the content root, is optional too, and only types reads it: the page types a page started there can be. The document can be any of the project’s files; from ascribe.toml, paths are written from the content root.

ascribe/edit

{
  "textDocument": { "uri": "file:///…/docs/install.md" },
  "range": { "start": { "line": 20, "character": 0 }, "end": { "line": 20, "character": 0 } },
  "action": "wrapNote",
  "args": { "type": "tip" },
  "version": 12
}

range is the cursor or selection the action was chosen at, action one of the actions below, and args what it needs, {} when left out. version, optional, is the document version the editor saw: when the document has changed since, the action is refused. An insertable line is one ascribe/context answers insertable for, a blank line between blocks. attributes is an object of key to value: a string, a number, a boolean, or a list for a set. Names, types, keys, pages, and the rest are checked against the project, and ascribe/targets lists the valid choices. ? marks an optional argument.

Action Applies to Its arguments What it writes
wrapNote One paragraph, or whole blocks type? (default note) @note before one paragraph, or a container (@note: … @end) around several blocks; {type=…} unless the type is note
setNoteType A note type The note’s type attribute, or none for note
unwrapNote A note The note’s content, without the directive
noteToDetails A note title .Title and @details, keeping the content and the form
wrapDetails One block, or whole blocks title .Title and @details (or @details: … @end)
unwrapDetails A details block Its content, without the title and the directive
makeSteps An ordered list @steps above it
removeSteps Steps The ordered list, without @steps
addHeadingId A heading without @id id? (default its slug) @id: … after the heading
insertNote An insertable line type?, text? A note; without text, a placeholder
insertSteps An insertable line count? (1 to 50, default 3) @steps and a numbered list of placeholders
insertVariantGroup An insertable line dimension, values One @variant {dimension=value}: arm per value, each with a placeholder, and @end
addVariantArm A group of one dimension’s arms value A new arm, in the dimension’s declared order
removeVariantArm An arm of a group with others The group without it
insertDetails An insertable line title .Title, @details:, a placeholder, @end
insertInclude An insertable line path (with #id for a section) @include: …
insertSnippet An insertable line address, lang?, title? @snippet: …, with the attributes given
insertImage An insertable line path, alt, attributes? An image of path, with alt as its text and the attributes after it
insertWidget An insertable line name, primary?, attributes? The widget, attributes in declared order; the container form with a placeholder when it takes one, and a .Title placeholder when its title is required
markAvailable A heading (its section), a block, or a table’s body row spec (a spec or a feature key) @available: … under the heading or before the block; for a row, {available=…} at the end of its first cell
setPageVariant Anywhere in a page dimension, value That dimension’s value under variant: in the frontmatter, keeping the rest
setPageAvailable Anywhere in a page spec available: in the frontmatter
setPageLabel Any of the project’s pages, open or not label? (none or empty to take it out) nav-label: in the frontmatter, a comment after it kept; nothing when it’s already so
linkSelection Prose selected in one paragraph or heading destination A link to destination, with the selection as its text
insertLink A cursor in prose destination A link to destination with empty text, so the target’s title fills it
insertPhrase A cursor in prose key {key}
setLinkTarget A link destination The link’s destination
useTargetTitle A link to a page Empty link text, so the target’s title fills it
setImageWidth An image width The image’s width attribute, when the model declares one
setImageAlt An image alt The image’s alt text
makePhrase Plain text selected in prose, on one line key, everywhere? (default false) key = "<the text>" in [phrases], and {key} in place of the selection; with everywhere, in place of each of its occurrences too
addGlossaryTerm Anywhere in a page term, definition, aliases? (a list) A section at the end of the first page [glossary] pages lists: the term as its heading, @term with the aliases, and the definition as its paragraph
promoteFeature Anywhere in a page key, spec The feature’s available in [features.<key>]
newPage Any of the project’s files: textDocument names the project, and range is unused type, title, folder? (a folder in the content root, as a file: URI) A new page, made by ascribe_templates::start: the type’s template with its title set, or its frontmatter when it has none, with type: first in its frontmatter, in folder or the content root, named for the title. Never over a file. select is the first thing the template left to fill in
moveSection Any of the project’s files, as newPage folder (a section’s folder from the content root, ending in /), before? (a sibling section’s folder; none for the end) ascribe.nav’s [[sections]] with the section before before among its siblings: the siblings it didn’t list are listed in the order they had, so nothing else moves
movePage Any of the project’s files, as newPage page (a content path), before? (a page of the same section; none for the end) The section’s pages, listing its pages as they stood with page before before; its table is added, and its siblings’, when the file doesn’t list it
placePage Any of the project’s files, as newPage page page at the end of its section’s pages, which leaves it out
setSectionLabel Any of the project’s files, as newPage folder, label? (none or empty for the default) The section’s label
setSetting Any of the project’s files, as newPage table (a dotted path, consumer; a check’s is checks.<check>, with the key level or limit), key, value (a boolean, a whole number, or a string, as the setting’s kind takes, or null to reset it to its default), shown (the version the ascribe/settings answer it was shown from had: a number, or null for the disk) The value where ascribe.toml writes it, as it is now, and nothing else; a value the file leaves out added after its table’s last entry, or in a new table at the end; or, for null, the setting’s line taken out with the comment lines touching it from above. A check is set in the form the file writes it (a level alone, an inline table, or a [checks.<check>] table). Refused when shown isn’t the version ascribe.toml has now, a buffer’s for the disk’s and the disk’s for a buffer’s included. Not refused for a problem the model then has, which ascribe/settings shows under the setting
nextPlaceholder A page of a type with a template Nothing: select is the next thing the template left to fill in after range, or the first when none is after it
addMemo Anywhere in a page A new memo file in memos/, its documentChanges creating it and giving it its text: about is the innermost section with an id at the cursor, as page.md#id, or the page above the first heading; quote is the selection, its whitespace runs as one space, or the first line of the block at the cursor, left out on a heading or when the memo wouldn’t find it. Named from the quote’s first words, or the heading’s id, never over a file. select is the empty line for the memo’s text. Refused when memos/ is in the content root
addPersonalMemo Anywhere in a page As addMemo, in .ascribe/memos/

ascribe/inventory

{ "textDocument": { "uri": "file:///…/ascribe.toml" } }

The document can be any of the project’s files.

ascribe/settings

{ "textDocument": { "uri": "file:///…/ascribe.toml" } }

The document can be any of the project’s files.

ascribe/page

{
  "textDocument": { "uri": "file:///…/docs/keys.md" },
  "position": { "line": 14, "character": 0 }
}

position picks the heading whose links and includes the result lists.

ascribe/projectEdit

{ "textDocument": { "uri": "file:///…/ascribe.toml" }, "kind": "fixAll" }

The document can be any of the project’s files. kind is fixAll, every safe fix of the problems last published for each file, or format, every file formatted as ascribe fmt formats it.

ascribe/buildView

{ "textDocument": { "uri": "file:///…/docs/guides/rollouts.md" }, "build": "self-hosted" }

build is optional, the editor’s build without it.

ascribe/search

{ "textDocument": { "uri": "file:///…/ascribe.toml" }, "query": "\"sign in to quill cloud\"", "build": "site" }

The document can be any of the project’s files. query is a query as ascribe search takes it, and build is optional: without it, every build is searched.

ascribe/agentPrompt

{
  "kind": "problem",
  "textDocument": { "uri": "file:///…/docs/guides/install.md" },
  "diagnostic": { "range": { "start": { "line": 3, "character": 0 }, "end": { "line": 3, "character": 12 } }, "code": "ASC036", "message": "…" },
  "unsaved": ["file:///…/docs/guides/install.md"],
  "program": "/…/bin/linux-x64/ascribe"
}

kind is what the prompt is about:

Kind About It also takes
problem One problem textDocument, and diagnostic, as the server published it
file A file’s problems textDocument
project The project’s problems textDocument, optional, to name the project
pageChanges What changed on a page, while review is on textDocument, and build, optional, the editor’s build without it
fragmentReach The pages that changed through a fragment, while review is on fragment, a content path, and build, as pageChanges

Every kind takes unsaved, the URIs of the documents with unsaved changes, so a prompt about one says to save it first, and program, optional, what the prompt’s commands start with when ascribe isn’t the binary the editor runs. Without program, they start with ascribe.