Skip to content

Commit 78989eb

Browse files
claudeclaude
committed
docs(vscode): lead the VS Code page with the install decision
Rewrite docs/guides/editors/vscode.md for a reader who arrives searching for a Markdown linter/formatter or a markdownlint alternative. Lead with what the extension does and the markdownlint comparison, keep the feature value props and the install channels, and drop the post-install configuration detail that only matters after the decision is made. Move the settings table and the troubleshooting cases into a new docs/reference/vscode-extension.md reference page and repoint the `mdsmith lsp` "See also". Regenerate the doc catalogs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QWRuDRqngK4NrU8FkWFByB
1 parent 0314c10 commit 78989eb

7 files changed

Lines changed: 129 additions & 81 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -147,6 +147,7 @@ row: "- [{summary}](../{filename})"
147147
- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](../docs/reference/schema-types.md)
148148
- [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](../docs/reference/section-schema.md)
149149
- [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](../docs/reference/telemetry.md)
150+
- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](../docs/reference/vscode-extension.md)
150151
<?/catalog?>
151152

152153
### Development Workflow

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,7 @@ row: "- [{summary}]({filename})"
153153
- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
154154
- [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](docs/reference/section-schema.md)
155155
- [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](docs/reference/telemetry.md)
156+
- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](docs/reference/vscode-extension.md)
156157
<?/catalog?>
157158

158159
## Development Workflow

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ row: "- [{summary}]({filename})"
139139
- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](docs/reference/schema-types.md)
140140
- [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](docs/reference/section-schema.md)
141141
- [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](docs/reference/telemetry.md)
142+
- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](docs/reference/vscode-extension.md)
142143
<?/catalog?>
143144

144145
## Development Workflow

‎docs/guides/editors/vscode.md‎

Lines changed: 31 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,24 @@ summary: >-
77
---
88
# mdsmith for VS Code
99

10-
The mdsmith extension puts the linter, the formatter, and
11-
cross-file navigation in your editor. It runs the same rule
12-
engine as `mdsmith check` on the command line and in CI, so a
13-
file that is clean as you edit is clean in the pipeline.
14-
Diagnostics, quick fixes, and navigation all come from one
15-
bundled binary, with nothing else to install.
10+
mdsmith is a Markdown linter and formatter that runs inside
11+
VS Code. It flags style, readability, structure, and broken
12+
cross-file links as you type, and fixes what fixes cleanly on
13+
save. The editor runs the same rule engine as `mdsmith check`
14+
on the command line and in CI, so a file that is clean as you
15+
edit is clean in the pipeline.
1616

1717
If you use markdownlint today, mdsmith covers the same style
18-
rules and adds cross-file checks. `mdsmith init
18+
rules and adds checks markdownlint has no model for: links
19+
and anchors across files, generated sections, heading and
20+
front-matter schemas, and readability budgets. `mdsmith init
1921
--from-markdownlint` converts your config in one command; the
2022
[migration guide](../migrate-from-markdownlint.md) covers the
2123
rest of the move.
2224

25+
Diagnostics, quick fixes, and navigation all come from one
26+
bundled binary, with nothing else to install.
27+
2328
## What you get
2429

2530
Each feature links to a page with its rules and examples.
@@ -51,15 +56,8 @@ clicked.
5156

5257
Each save then fixes trailing whitespace, heading style, code
5358
fences, bare URLs, list indentation, and table alignment.
54-
55-
**Preview fix-on-save.** Enable `mdsmith.previewFix` and
56-
fix-on-save routes through VS Code's Refactor Preview pane, so
57-
you see the diff and confirm it before `source.fixAll.mdsmith`
58-
writes it on save. Interactive lightbulb quick fixes always
59-
apply immediately — they are the one fix you just chose, so
60-
there is nothing to confirm. To preview a single quick fix,
61-
use VS Code's built-in lightbulb Preview (the chevron, or
62-
Ctrl+Enter).
59+
Enable `mdsmith.previewFix` to see the diff in VS Code's
60+
Refactor Preview before each save writes.
6361

6462
**Hover for help.** Hover a diagnostic for the rule's one-line
6563
summary plus a link that opens its full documentation offline:
@@ -124,75 +122,29 @@ codium --install-extension jeduden.mdsmith
124122
code --install-extension mdsmith-<version>.vsix
125123
```
126124

127-
You need VS Code 1.85 or later. A config file is optional:
128-
mdsmith lints with built-in defaults, so the extension works
129-
as soon as you install it. To tune the rules, run the
130-
**mdsmith: Initialize Config** command, which writes a starter
131-
`.mdsmith.yml`. The server then finds that file by walking up
132-
from the workspace root to the nearest `.mdsmith.yml` or
133-
`.git`, the same as `mdsmith check`. See
125+
You need VS Code 1.85 or later. See
134126
[Installation: VS Code extension](../install.md#vs-code-extension)
135127
for the channel-by-channel breakdown.
136128

137-
## Settings
138-
139-
Project overrides go in `.vscode/settings.json`; global
140-
preferences go in your user settings. Changing any setting
141-
takes effect on the next document event, with no window
142-
reload.
143-
144-
| Setting | Default | Purpose |
145-
| ---------------------- | --------- | ----------------------------------------------------------------------------------------- |
146-
| `mdsmith.run` | `onType` | When to lint: `onType` (default), `onSave`, or `off` (off stops automatic linting) |
147-
| `mdsmith.previewFix` | `false` | Show the diff (Refactor Preview) before fix-on-save writes; quick fixes apply immediately |
148-
| `mdsmith.config` | `""` | Override the `.mdsmith.yml` path (absolute or workspace) |
149-
| `mdsmith.path` | `mdsmith` | Pin a binary; the default runs the bundled per-platform one |
150-
| `mdsmith.trace.server` | `off` | LSP trace verbosity: `off`, `messages`, or `verbose` |
151-
152-
`mdsmith.run` defaults to `onType`, so diagnostics update live
153-
as you type; `onSave` defers them to save, and `off` stops
154-
them entirely (quick fixes still work on demand).
155-
156-
Fix-on-save is configured through VS Code's native
157-
`editor.codeActionsOnSave`, shown above under **Fix on save** —
158-
not through an mdsmith setting. The former `mdsmith.fixOnSave`
159-
toggle is now a deprecated no-op. Fix-on-save runs independently
160-
of `mdsmith.run`, and `mdsmith.previewFix` decides whether each
161-
save shows the diff before writing. `mdsmith.previewFix` governs
162-
fix-on-save only; interactive lightbulb quick fixes always apply
163-
immediately (use the lightbulb's own Preview to inspect one).
164-
165-
## Troubleshooting
166-
167-
**No diagnostics appear.** Confirm the binary resolves: open
168-
the integrated terminal and run `mdsmith version`. If it is
169-
not found, set `mdsmith.path` to an absolute path. Set
170-
`mdsmith.trace.server` to `messages` and read the "mdsmith"
171-
Output channel.
172-
173-
**`spawn mdsmith ENOENT`.** Reachable only when you set
174-
`mdsmith.path` to a bare name and your platform was not
175-
bundled. The extension host does not source `~/.bashrc`, so a
176-
`go install` location such as `~/go/bin` is invisible to it.
177-
Clear `mdsmith.path` to use the bundled binary, or set it to
178-
an absolute path.
179-
180-
**Server crashed too many times.** The restart limiter
181-
tripped because the binary crashes on every request. Open the
182-
"mdsmith" Output channel for the stack trace, fix the cause,
183-
then run `mdsmith: Restart Language Server`.
184-
185-
**Two mdsmith servers running; I want one.** A reload or
186-
update can leave the old extension host alive next to the new
187-
one, each running its own server. The newest server wins: it
188-
claims the workspace and the older one exits, sending an
189-
`mdsmith/superseded` notice first so the client does not
190-
restart it. If an older build left an orphan, kill its
191-
extension host once — not the `mdsmith` process, which the
192-
host respawns.
129+
## Settings and troubleshooting
130+
131+
A config file is optional: mdsmith lints with built-in
132+
defaults, so the extension works as soon as you install it. To
133+
tune the rules, run the **mdsmith: Initialize Config** command,
134+
which writes a starter `.mdsmith.yml`. The server then finds
135+
that file by walking up from the workspace root to the nearest
136+
`.mdsmith.yml` or `.git`, the same as `mdsmith check`.
137+
138+
For the full settings table — `mdsmith.run`, `mdsmith.path`,
139+
`mdsmith.config`, `mdsmith.previewFix`, and
140+
`mdsmith.trace.server` — and fixes for common failure modes,
141+
see the
142+
[VS Code extension reference](../../reference/vscode-extension.md).
193143

194144
## See also
195145

146+
- [VS Code extension reference](../../reference/vscode-extension.md)
147+
— the settings table and troubleshooting
196148
- [`mdsmith lsp`](../../reference/cli/lsp.md) — the protocol
197149
reference: capabilities, diagnostic mapping, symbol
198150
navigation, and the latency budget

‎docs/reference/cli/lsp.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -296,5 +296,7 @@ the p95 latency benchmarks (150 ms on 1 000-line, 500 ms on
296296

297297
- [`mdsmith check`](check.md) — the CLI surface that the server reuses
298298
- [`mdsmith fix`](fix.md) — the fix pipeline behind both code actions
299-
- [VS Code guide](../../guides/editors/vscode.md) — install,
300-
settings, troubleshooting
299+
- [VS Code guide](../../guides/editors/vscode.md) — what the
300+
extension does and how to install it
301+
- [VS Code extension reference](../vscode-extension.md) — the
302+
settings table and troubleshooting

‎docs/reference/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,4 +44,5 @@ row: "- [{summary}]({filename})"
4444
- [Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.](schema-types.md)
4545
- [Section-schema reference for inline `kinds.<name>.schema:` blocks. Covers the `heading:` discriminator, the `regex:` matcher (a Go RE2 body with `\#(digits)` and `\#(fmvar(...))` helpers), the `repeat: {min, max}` cardinality field, and the matching algorithm. `proto.md` files are parsed into the same shape by the schema package, but MDS020's file-schema check still uses its legacy parser; see the proto.md section below for what is and is not migrated.](section-schema.md)
4646
- [mdsmith collects no telemetry, no usage analytics, no error reports, and no identifiers. The CLI and the LSP server make no outbound network calls at runtime.](telemetry.md)
47+
- [Settings and troubleshooting for the mdsmith VS Code extension: the five `mdsmith.*` settings, fix-on-save wiring, and fixes for its known failure modes.](vscode-extension.md)
4748
<?/catalog?>

‎docs/reference/vscode-extension.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
weight: 45
3+
summary: >-
4+
Settings and troubleshooting for the mdsmith VS Code
5+
extension: the five `mdsmith.*` settings, fix-on-save
6+
wiring, and fixes for its known failure modes.
7+
---
8+
# mdsmith VS Code extension
9+
10+
The mdsmith VS Code extension is a thin LSP client over the
11+
bundled `mdsmith` binary, which it runs with the `lsp`
12+
subcommand. This page lists the extension's settings and the
13+
fixes for its known failure modes. For what the extension
14+
does and how to install it, see the
15+
[VS Code guide](../guides/editors/vscode.md).
16+
17+
## Settings
18+
19+
Project overrides go in `.vscode/settings.json`; global
20+
preferences go in user settings. A changed setting takes
21+
effect on the next document event, with no window reload.
22+
23+
| Setting | Default | Purpose |
24+
| ---------------------- | --------- | ----------------------------------------------------------------------------------------- |
25+
| `mdsmith.run` | `onType` | When to lint: `onType` (default), `onSave`, or `off` (off stops automatic linting) |
26+
| `mdsmith.previewFix` | `false` | Show the diff (Refactor Preview) before fix-on-save writes; quick fixes apply immediately |
27+
| `mdsmith.config` | `""` | Override the `.mdsmith.yml` path (absolute or workspace) |
28+
| `mdsmith.path` | `mdsmith` | Pin a binary; the default runs the bundled per-platform one |
29+
| `mdsmith.trace.server` | `off` | LSP trace verbosity: `off`, `messages`, or `verbose` |
30+
31+
`mdsmith.run` controls automatic linting. `onType` updates
32+
diagnostics live as text changes. `onSave` defers them to
33+
save. `off` stops automatic linting; quick fixes still run
34+
on demand.
35+
36+
`mdsmith.config` overrides config discovery. Without it, the
37+
server walks up from the workspace root to the nearest
38+
`.mdsmith.yml` or `.git`, the same as `mdsmith check`.
39+
40+
## Fix on save
41+
42+
Fix-on-save is configured through VS Code's native
43+
`editor.codeActionsOnSave`, not an mdsmith setting. The
44+
[VS Code guide](../guides/editors/vscode.md) shows the
45+
`source.fixAll.mdsmith` entry. The former `mdsmith.fixOnSave`
46+
toggle is now a deprecated no-op.
47+
48+
Fix-on-save runs independently of `mdsmith.run`.
49+
`mdsmith.previewFix` governs fix-on-save only. When it is
50+
`true`, each save routes through VS Code's Refactor Preview
51+
pane and shows the diff before the edit writes. Interactive
52+
lightbulb quick fixes always apply immediately, since each is
53+
the one fix just chosen.
54+
55+
## Troubleshooting
56+
57+
**No diagnostics appear.** The binary did not resolve. Run
58+
`mdsmith version` in the integrated terminal. If the command
59+
is not found, set `mdsmith.path` to an absolute path. Set
60+
`mdsmith.trace.server` to `messages` and read the "mdsmith"
61+
Output channel.
62+
63+
**`spawn mdsmith ENOENT`.** This is reachable only when
64+
`mdsmith.path` is a bare name and the running platform was
65+
not bundled. The extension host does not source `~/.bashrc`,
66+
so a `go install` location such as `~/go/bin` is invisible to
67+
it. Clear `mdsmith.path` to use the bundled binary, or set it
68+
to an absolute path.
69+
70+
**Server crashed too many times.** The restart limiter
71+
tripped because the binary crashes on every request. Open the
72+
"mdsmith" Output channel for the stack trace, fix the cause,
73+
then run **mdsmith: Restart Language Server**.
74+
75+
**Two mdsmith servers running.** A reload or update can leave
76+
the old extension host alive next to the new one, each with
77+
its own server. The newest server wins: it claims the
78+
workspace, and the older one exits after sending an
79+
`mdsmith/superseded` notice so the client does not restart
80+
it. If an older build left an orphan, kill its extension host
81+
once — not the `mdsmith` process, which the host respawns.
82+
83+
## See also
84+
85+
- [VS Code guide](../guides/editors/vscode.md) — what the
86+
extension does and how to install it
87+
- [`mdsmith lsp`](cli/lsp.md) — the protocol reference:
88+
capabilities, diagnostic mapping, and symbol navigation
89+
- [`mdsmith check`](cli/check.md) and [`mdsmith fix`](cli/fix.md)
90+
— the CLI surfaces the extension reuses

0 commit comments

Comments
 (0)