markdown-lsp 1.3.0 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +52 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -8,7 +8,10 @@
|
|
|
8
8
|
|
|
9
9
|
CLI and library for querying Markdown documentation graphs. Point it at a folder of `.md` files and get instant full-text search, outline, link analysis, symbol lookup, interactive HTML graphs, and AI-powered semantic search at page, heading, or paragraph granularity — all as JSON.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
<img width="1709" height="980" alt="Screenshot 2026-06-22 at 13 37 53" src="https://github.com/user-attachments/assets/5c540cd3-d5c0-48ca-90fa-645a266cb0f7" />
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
**Status: v1.4.0. CLI is the default interface. LSP stdio mode available as a subcommand.**
|
|
12
15
|
|
|
13
16
|
---
|
|
14
17
|
|
|
@@ -65,6 +68,41 @@ npx markdown-lsp lsp --stdio
|
|
|
65
68
|
|
|
66
69
|
---
|
|
67
70
|
|
|
71
|
+
## Quick Start with Claude Code (skill)
|
|
72
|
+
|
|
73
|
+
Install the skill once — then ask Claude Code natural-language questions about your docs directly in chat:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
npx skills add Docsbook-io/markdown-lsp
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
After installation, Claude Code will guide you through setup interactively. Just ask:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
set up markdown-lsp for my project
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The skill will ask you questions step by step — docs folder, API key, granularity — and configure everything in chat. Other things you can ask once installed:
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
build a semantic index of ./docs
|
|
89
|
+
search my docs semantically for "how to configure webhooks"
|
|
90
|
+
show me which pages link to getting-started.md
|
|
91
|
+
find sections about rate limiting (heading-level search)
|
|
92
|
+
show me a semantic graph of my docs
|
|
93
|
+
set up a git hook to keep the index fresh after each merge
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
For semantic search and the graph, you need a free [OpenRouter](https://openrouter.ai/keys) key:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
export OPENROUTER_API_KEY=sk-or-...
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The skill sets everything up in chat — index, git hooks, and the interactive graph.
|
|
103
|
+
|
|
104
|
+
---
|
|
105
|
+
|
|
68
106
|
## Installation
|
|
69
107
|
|
|
70
108
|
```bash
|
|
@@ -201,6 +239,19 @@ If a file changes, its hash changes, so it is re-embedded automatically (no stal
|
|
|
201
239
|
| After `index --granularity heading` (~1190 sections) | 1 (query only) | ~1/1190 |
|
|
202
240
|
| `index` re-run with no changes | 0 | free |
|
|
203
241
|
|
|
242
|
+
### Incremental & token-saving: re-run `index` anytime
|
|
243
|
+
|
|
244
|
+
`index ./docs` is incremental by design — only changed units are re-embedded, unchanged ones are
|
|
245
|
+
served from the local cache (`.markdown-lsp-cache/embeddings/`). You can call it as frequently as
|
|
246
|
+
you like without wasting API tokens on content that hasn't changed.
|
|
247
|
+
|
|
248
|
+
To automate re-indexing, the recommended approach is a **git hook** (no extra deps, no debounce
|
|
249
|
+
complexity): a `post-merge` or `post-checkout` hook runs `npx markdown-lsp index ./docs` automatically
|
|
250
|
+
after pulls and branch switches. For real-time updates while writing docs, a debounced watch script
|
|
251
|
+
(stdlib `fs.watch` with a 3-5 s debounce) works well. CI users can cache `.markdown-lsp-cache/`
|
|
252
|
+
via `actions/cache` so the index survives across runs. See the [skill file](.claude/skills/markdown-lsp/SKILL.md)
|
|
253
|
+
for ready-to-use snippets for all three patterns.
|
|
254
|
+
|
|
204
255
|
---
|
|
205
256
|
|
|
206
257
|
## Semantic search with granularity
|
package/package.json
CHANGED