A markdown predicate linter and backlink reconciler, shipped as an LSP server.
Lattice encodes link predicates in CommonMark title text and maintains backlinks in YAML frontmatter. The graph lives in the files themselves — no database, everything in git.
cargo install latticeOr download a prebuilt binary (Linux, macOS, Windows) from the latest release. Building from source needs Rust 1.95 or newer.
# Lint all markdown files in the current project (exit 1 on errors)
lattice lint
# Run as an LSP server (used by editors)
lattice serve
# Print the full configuration reference (every option, with defaults)
lattice config
# Print the version (with git commit and dirty state)
lattice --versionLattice is not shipped by nvim-lspconfig, so configure it directly.
On Neovim 0.11+:
vim.lsp.config.lattice = {
cmd = { "lattice", "serve" },
filetypes = { "markdown" },
root_markers = { ".lattice.toml", ".git" },
}
vim.lsp.enable("lattice")Diagnostics appear inline on open, change, and save. When the editor
supports LSP dynamic file-watch registration
(workspace/didChangeWatchedFiles), Lattice also registers watches for
.lattice.toml and project .md files, so config edits hot-reload (no
restart) and on-disk changes made outside the editor (e.g. a git checkout) update the graph live; without that support, both apply only
on restart. Lattice is
diagnostic-first, but the server is a full markdown LSP: completion
(paths, headings, predicates, reference labels, footnotes), hover,
document and workspace symbols, references, rename, folding, document
links, formatting, semantic tokens (emphasis styling, below), and
go-to-definition/declaration/type/implementation plus call and type
hierarchy over the predicate graph.
Lattice emits semantic tokens for emphasis runs: one token type,
markup, carrying bold, italic, and strikethrough modifiers.
Neovim maps each modifier to an @lsp.mod.<name> highlight group, and
neither Neovim core nor common colorschemes define these, so the tokens
paint nothing until you do — once, after your colorscheme loads (a
ColorScheme autocmd survives reloads):
vim.api.nvim_set_hl(0, "@lsp.mod.bold", { bold = true })
vim.api.nvim_set_hl(0, "@lsp.mod.italic", { italic = true })
vim.api.nvim_set_hl(0, "@lsp.mod.strikethrough", { strikethrough = true })Tokens are served for any opened markdown document, rooted or not: a
scratch file outside every workspace root (a note in /tmp, say) gets
the same emphasis styling as a project file. Workspace roots gate only
the graph-linting tier — backlinks, predicates, connectivity.
Treesitter's own markdown emphasis highlighting stays active alongside,
and extmark attributes merge — so a span the grammar gets wrong stays
lit no matter what Lattice says (tree-sitter-markdown-inline
approximates GFM flanking rules and will, for example, pair a
single-tilde strikethrough across a soft line break). To hand emphasis
styling to Lattice entirely, blank the language-qualified treesitter
groups; the qualified name shadows the generic @markup.* for markdown
only, and every other filetype keeps its styling:
vim.api.nvim_set_hl(0, "@markup.strong.markdown_inline", {})
vim.api.nvim_set_hl(0, "@markup.italic.markdown_inline", {})
vim.api.nvim_set_hl(0, "@markup.strikethrough.markdown_inline", {})Leave treesitter itself enabled for markdown: it still provides the structural highlighting (headings, links, code spans) and the injected highlighting inside fenced code blocks; only its emphasis captures go quiet. Emphasis styling then updates at semantic-token cadence (on server response) rather than per keystroke.
On Neovim older than 0.11, start it per buffer instead:
vim.api.nvim_create_autocmd("FileType", {
pattern = "markdown",
callback = function(args)
vim.lsp.start({
name = "lattice",
cmd = { "lattice", "serve" },
root_dir = vim.fs.root(args.buf, { ".lattice.toml", ".git" }),
})
end,
})Both lattice lint and lattice format --check share one exit-code
contract, so they slot into any gate: exit 0 = clean, exit 1 = errors
(a broken link, unknown predicate, or unformatted frontmatter). Warnings
— missing backlinks, bare paths — do not fail the build; pass
--strict to lattice lint to gate on those too. So a PR with a broken
link fails, a warnings-only PR passes, and a clean project passes
silently.
lattice format --check writes nothing: it exits 1 and lists any file
whose backlink frontmatter is not sorted/normalized, and exits 0 when
every file is already formatted. Run lattice format (no --check) to
rewrite them in place — this is a graph no-op, changing only frontmatter
bytes, never the diagnostics lattice lint produces.
Both commands check the scope they are invoked in and stop at every nested-scope boundary (see Nested scopes): one invocation, one graph. In a repository containing nested scopes, run each once from every marker directory.
Reference the bundled composite action from a workflow. It installs
lattice, runs lattice lint, then lattice format --check:
# .github/workflows/lattice.yml
name: Lattice
on: [push, pull_request]
jobs:
lattice:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: TwoWells/Lattice/.github/actions/lattice@v1
# with:
# version: "0.4.1" # pin a crates.io version (default: latest)
# path: "docs" # scope to a subtree (default: repo root)
# strict: "true" # also fail on warnings (default: false)
# format-check: "false" # skip the format gate (default: true)For projects using pre-commit, add Lattice as a
hook repo in .pre-commit-config.yaml:
repos:
- repo: https://github.com/TwoWells/Lattice
rev: v0.4.1
hooks:
- id: lattice-lint
- id: lattice-format-checklattice-format-check fails the commit on unformatted frontmatter; run
lattice format to fix it. Drop the lattice-format-check entry if you
only want the graph lint.
Without pre-commit, add to .githooks/pre-commit or
.git/hooks/pre-commit:
#!/bin/sh
lattice lint && lattice format --checkCommits with broken links, unknown predicates, missing backlinks, or unformatted frontmatter will be rejected.
An optional .lattice.toml at the project root overrides defaults:
[predicates]
supersedes = "superseded_by"
implements = "implemented_by"
depends_on = "dependency_of"
amends = "amended_by"
blocks = "blocked_by"
references = "referenced_by"
[policy]
predicates = "optional" # or "required"
backlinks = true
bare_paths = "warn" # or "deny", "disabled"
stale_references = "warn" # or "hint", "deny", "disabled" — dangling `.md` references
# fragments = "github" # or "gitlab", "vscode"; omit to try all
# connectivity = "off" # or "no-orphans", "no-islands", "reachable"
# roots = ["README.md"] # entry points for "reachable"; default = root README
# Opt-in convention checks (off by default — they flag valid CommonMark, not defects):
# code_block_language = "disabled" # or "hint", "warn", "deny" — flag untagged code fences
# multiple_h1 = false # flag more than one H1 heading
# skipped_heading_level = false # flag a skipped heading level (e.g. H1 -> H3)
# image_empty_alt = false # flag images with empty alt text
# Cross-repo references: a `{Name}/path` citation (backtick/quoted/bare, not a
# link) is checked existence-only against an aliased directory — never read,
# indexed, or treated as a graph edge. An undefined alias, or one whose
# directory is absent, is exempt; a present directory with a missing file is a
# stale reference. Relative (sibling-checkout) values are preferred.
# [external]
# Themis = "../Themis"A .lattice.toml marks the root of a graph. A nested .lattice.toml (or a
nested .git — a submodule or vendored repo) marks the root of a different,
smaller graph: the marker partitions the tree into disjoint scopes, each
self-describing under its own marker (never the outer vocabulary), and each
behaving exactly as if it were a sibling. Membership stops at every
strictly-deeper marker, so no backlink expectation crosses a boundary in either
direction. Discovery is entry-point independent — linting from the outer root,
from inside the nested scope, or via an editor session rooted at either agrees
on where each graph begins. A nested .git without its own .lattice.toml is a
non-root environment: excluded from the host graph and never indexed.
A plain relative link (or a ../ escape) whose target lands in another scope is
a defect, not a reference — it errors with link target … is outside this scope — reference it through an [external] alias (a boundary-crossing path-shaped
mention is its warn-tier sibling). Rewrite it as a {Name}/path citation and
alias Name in the referrer's own [external] table. Reach for a nested marker
when a subtree is a separable unit (its own graph); reach for an
[[override]] when a subtree just wants different strictness within one
graph.
Migration. Before this release a nested
.lattice.tomlwas inert — its subtree was swallowed into the outer graph. It now splits into its own graph: cross-boundary plain links surface as steering errors, and stale backlink entries across the boundary become removable. This is a one-time, diagnostic-guided cleanup; stage large ones with[[override]]count-keys.
A path-shaped string that is deliberately not a live reference (a worked
example, a counterexample, a knowingly-dead link) can be excepted from the
stale_references / bare_paths lints in the document's own frontmatter,
keyed by the literal reference with a required reason as the value:
---
exceptions:
stale_references:
"tickets/acquire/DESIGN.md": "hypothetical path in the worked example"
"{Themis}/old/layout.md": "pre-refactor path, kept for the changelog note"
bare_paths:
"README.md": "naming the file, deliberately not a link"
---Exceptions are reconciled like backlinks, not silenced: an entry that matches
no live diagnostic — its reference gone, or now resolving — is itself flagged
as an unused exception whose message echoes the stored reason, and an entry
with an empty reason is flagged too. Lattice flags, never auto-removes — the
reason is the surviving record of a vanished reference's intent. A {Name}/…
key flows through identically. An exception is never a graph edge and imposes
no backlink obligation.
Add this to your project's AGENTS or CLAUDE file:
Markdown links follow Lattice conventions: predicates are encoded in title text, e.g.
[Doc](doc.md "supersedes"). The predicate vocabulary is: supersedes, implements, depends_on, amends, blocks, references. Backlinks are maintained in YAML frontmatter.
AGPL-3.0-or-later. Commercial license available — contact Two Wells.