dead-links 0.3.0 → 0.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 +60 -248
- package/dist/index.js +298 -757
- package/dist/index.js.map +1 -1
- package/package.json +15 -14
package/README.md
CHANGED
|
@@ -1,298 +1,110 @@
|
|
|
1
1
|
# dead-links
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Scan an Obsidian vault for broken links, orphan notes, and note connections. Run commands from the vault directory for the shortest workflow, or pass `--vault` when working elsewhere.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Quick start
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
npx dead-links scan --vault "my-vault"
|
|
9
|
-
npx dead-links broken --vault "my-vault" --verbose
|
|
10
|
-
npx dead-links orphans --vault "my-vault" --ignore-folders Films Diary
|
|
11
|
-
npx dead-links graph --vault "my-vault" --format json
|
|
12
|
-
npx dead-links report --vault "my-vault" --output report.md
|
|
13
|
-
```
|
|
14
|
-
|
|
15
|
-
## Commands
|
|
16
|
-
|
|
17
|
-
| Command | Description |
|
|
18
|
-
|---------|-------------|
|
|
19
|
-
| `dead-links scan` | Full scan: broken links + orphan notes + graph |
|
|
20
|
-
| `dead-links broken` | Show only broken links with smart suggestions |
|
|
21
|
-
| `dead-links orphans` | Show only orphan notes |
|
|
22
|
-
| `dead-links graph` | Show connection graph |
|
|
23
|
-
| `dead-links report` | Generate a `.md` report file |
|
|
24
|
-
| `dead-links stats` | **NEW** Show detailed vault statistics |
|
|
25
|
-
|
|
26
|
-
### scan
|
|
7
|
+
From the vault directory:
|
|
27
8
|
|
|
28
9
|
```bash
|
|
29
|
-
dead-links scan
|
|
30
|
-
|
|
31
|
-
Options:
|
|
32
|
-
--vault <path> Path to the Obsidian vault (default: current directory)
|
|
33
|
-
--format <type> Output format: text, json, markdown, csv, html, mermaid, dot (default: text)
|
|
34
|
-
--output <file> Save output to a file
|
|
35
|
-
--ignore <patterns...> Glob patterns to ignore
|
|
36
|
-
--attachments Also check embedded attachments (images, PDFs)
|
|
37
|
-
--ignore-folders <folders> Exclude folders from orphan report
|
|
38
|
-
--quiet Only show issues, no stats
|
|
39
|
-
--no-color Disable colored output
|
|
40
|
-
--suggestions Show smart suggestions for broken links
|
|
41
|
-
--debug Enable debug mode with verbose output
|
|
42
|
-
--fix Auto-fix broken links using generated suggestions
|
|
10
|
+
npx dead-links scan
|
|
11
|
+
npx dead-links report --output dead-links-report.md
|
|
43
12
|
```
|
|
44
13
|
|
|
45
|
-
|
|
14
|
+
From another directory:
|
|
46
15
|
|
|
47
16
|
```bash
|
|
48
|
-
dead-links
|
|
49
|
-
|
|
50
|
-
Options:
|
|
51
|
-
--vault <path> Path to the Obsidian vault (default: current directory)
|
|
52
|
-
--ignore <patterns...> Glob patterns to ignore
|
|
53
|
-
--attachments Also check embedded attachments
|
|
54
|
-
--verbose Show line numbers and full details
|
|
55
|
-
--suggestions Show smart suggestions for broken links
|
|
56
|
-
--debug Enable debug mode
|
|
17
|
+
npx dead-links scan --vault "D:/Notes/MyVault"
|
|
18
|
+
npx dead-links report --vault "D:/Notes/MyVault" --output report.md
|
|
57
19
|
```
|
|
58
20
|
|
|
59
|
-
|
|
21
|
+
`scan` prints results in the terminal by default. `report` saves a Markdown report. Both use the current directory as the vault unless `--vault` is provided.
|
|
60
22
|
|
|
61
|
-
|
|
62
|
-
dead-links orphans [options]
|
|
63
|
-
|
|
64
|
-
Options:
|
|
65
|
-
--vault <path> Path to the Obsidian vault (default: current directory)
|
|
66
|
-
--ignore <patterns...> Glob patterns to ignore
|
|
67
|
-
--ignore-folders <folders> Exclude folders from report
|
|
68
|
-
--verbose Show full list of orphan notes
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
### graph
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
dead-links graph [options]
|
|
23
|
+
## Commands
|
|
75
24
|
|
|
76
|
-
|
|
77
|
-
--vault <path> Path to the Obsidian vault (default: current directory)
|
|
78
|
-
--format <type> Output format: text, json (default: text)
|
|
79
|
-
--ignore <patterns...> Glob patterns to ignore
|
|
80
|
-
```
|
|
25
|
+
### `scan`
|
|
81
26
|
|
|
82
|
-
|
|
27
|
+
Analyze the vault and print or export the results.
|
|
83
28
|
|
|
84
29
|
```bash
|
|
85
|
-
dead-links
|
|
86
|
-
|
|
87
|
-
Options:
|
|
88
|
-
--vault <path> Path to the Obsidian vault (default: current directory)
|
|
89
|
-
--output <file> Output file path (default: dead-links-report.md)
|
|
90
|
-
--ignore <patterns...> Glob patterns to ignore
|
|
30
|
+
dead-links scan [options]
|
|
91
31
|
```
|
|
92
32
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
• Total notes and links count
|
|
105
|
-
• Average links per note
|
|
106
|
-
• Vault health score
|
|
107
|
-
• Most connected notes
|
|
108
|
-
• Orphan notes preview
|
|
109
|
-
• Connected components
|
|
110
|
-
```
|
|
33
|
+
| Option | Description |
|
|
34
|
+
|--------|-------------|
|
|
35
|
+
| `--vault <path>` | Vault directory (default: current directory) |
|
|
36
|
+
| `--format <type>` | Output format: `text`, `json`, `markdown`, `csv`, or `html` (default: `text`) |
|
|
37
|
+
| `--output <file>` | Write results to a file instead of the terminal |
|
|
38
|
+
| `--ignore <patterns...>` | Glob patterns to skip |
|
|
39
|
+
| `--attachments` | Check embedded attachments such as images and PDFs |
|
|
40
|
+
| `--ignore-folders <folders...>` | Exclude folders from orphan-note results |
|
|
41
|
+
| `--quiet` | In text format, print only findings |
|
|
42
|
+
| `--no-color` | Disable colors in text output |
|
|
43
|
+
| `--debug` | Print additional scan details |
|
|
111
44
|
|
|
112
|
-
|
|
45
|
+
Examples:
|
|
113
46
|
|
|
114
47
|
```bash
|
|
115
|
-
# Full scan with suggestions
|
|
116
|
-
npx dead-links scan --vault "my-vault" --suggestions
|
|
117
|
-
|
|
118
|
-
# Check for broken links with suggestions
|
|
119
|
-
npx dead-links broken --vault "my-vault" --suggestions
|
|
120
|
-
|
|
121
|
-
# Detailed vault statistics
|
|
122
|
-
npx dead-links stats --vault "my-vault"
|
|
123
|
-
|
|
124
48
|
# Interactive HTML report
|
|
125
|
-
npx dead-links scan --
|
|
126
|
-
|
|
127
|
-
# CSV export for spreadsheets
|
|
128
|
-
npx dead-links scan --vault "my-vault" --format csv --output issues.csv
|
|
129
|
-
|
|
130
|
-
# Graph visualization (Mermaid diagram)
|
|
131
|
-
npx dead-links scan --vault "my-vault" --format mermaid --output graph.md
|
|
132
|
-
|
|
133
|
-
# Graph visualization (GraphViz/DOT format)
|
|
134
|
-
npx dead-links scan --vault "my-vault" --format dot --output graph.dot
|
|
135
|
-
|
|
136
|
-
# Markdown report
|
|
137
|
-
npx dead-links report --vault "my-vault" --output report.md
|
|
138
|
-
|
|
139
|
-
# Debug mode (verbose)
|
|
140
|
-
npx dead-links scan --vault "my-vault" --debug
|
|
141
|
-
|
|
142
|
-
# Include attachments in the check
|
|
143
|
-
npx dead-links scan --vault "my-vault" --attachments
|
|
144
|
-
|
|
145
|
-
# Ignore noisy folders from orphan report
|
|
146
|
-
npx dead-links scan --vault "my-vault" --ignore-folders Films Diary Books
|
|
147
|
-
|
|
148
|
-
# JSON output for scripts/CI
|
|
149
|
-
npx dead-links scan --vault "my-vault" --format json
|
|
150
|
-
|
|
151
|
-
# Ignore patterns
|
|
152
|
-
npx dead-links scan --vault "my-vault" --ignore "**/Templates/**" "**/.trash/**"
|
|
49
|
+
npx dead-links scan --format html --output report.html
|
|
153
50
|
|
|
154
|
-
#
|
|
155
|
-
npx dead-links scan --
|
|
51
|
+
# JSON output
|
|
52
|
+
npx dead-links scan --format json --output report.json
|
|
156
53
|
|
|
157
|
-
#
|
|
158
|
-
npx dead-links scan --
|
|
159
|
-
|
|
160
|
-
# Show orphan notes list
|
|
161
|
-
npx dead-links orphans --vault "my-vault" --verbose
|
|
54
|
+
# Skip template and trash folders
|
|
55
|
+
npx dead-links scan --ignore "**/Templates/**" "**/.trash/**"
|
|
162
56
|
```
|
|
163
|
-
## Opening Reports
|
|
164
|
-
|
|
165
|
-
After generating a report with `--output`, you can open it with:
|
|
166
57
|
|
|
167
|
-
|
|
168
|
-
# Windows
|
|
169
|
-
start report.html
|
|
58
|
+
### `report`
|
|
170
59
|
|
|
171
|
-
|
|
172
|
-
open report.html
|
|
173
|
-
|
|
174
|
-
# Linux
|
|
175
|
-
xdg-open report.html
|
|
176
|
-
|
|
177
|
-
# Or navigate to the file in your file explorer and double-click it
|
|
178
|
-
```
|
|
179
|
-
|
|
180
|
-
The generated files are saved in your current directory:
|
|
181
|
-
- `report.html` - Open in any web browser
|
|
182
|
-
- `issues.csv` - Open with Excel, Google Sheets, or any spreadsheet app
|
|
183
|
-
- `graph.md` - View in GitHub, Obsidian, or any markdown viewer
|
|
184
|
-
- `graph.dot` - Render with Graphviz: `dot -Tpng graph.dot -o graph.png`
|
|
185
|
-
## Output Format
|
|
60
|
+
Generate a Markdown report containing statistics, broken links, orphan notes, and connection summaries.
|
|
186
61
|
|
|
62
|
+
```bash
|
|
63
|
+
dead-links report [options]
|
|
187
64
|
```
|
|
188
|
-
Notes 368
|
|
189
|
-
Links 943
|
|
190
|
-
Broken links 5
|
|
191
|
-
Orphan notes 222
|
|
192
|
-
Components 248
|
|
193
65
|
|
|
194
|
-
|
|
66
|
+
| Option | Description |
|
|
67
|
+
|--------|-------------|
|
|
68
|
+
| `--vault <path>` | Vault directory (default: current directory) |
|
|
69
|
+
| `--output <file>` | Report path (default: `dead-links-report.md`) |
|
|
70
|
+
| `--ignore <patterns...>` | Glob patterns to skip |
|
|
195
71
|
|
|
196
|
-
|
|
197
|
-
[Missing Note 1]
|
|
198
|
-
[Missing Note 2]
|
|
72
|
+
## Output formats
|
|
199
73
|
|
|
200
|
-
|
|
201
|
-
|
|
74
|
+
- **Text** — scan statistics, broken links, and orphan notes in the terminal.
|
|
75
|
+
- **JSON** — machine-readable scan results, including note connections.
|
|
76
|
+
- **Markdown** — readable report with statistics, issues, orphan notes, and the most-connected notes.
|
|
77
|
+
- **CSV** — tabular issue data for spreadsheets.
|
|
78
|
+
- **HTML** — a responsive report with overview metrics, searchable issue tables, and note connections.
|
|
202
79
|
|
|
203
|
-
|
|
80
|
+
Files are written relative to the current directory unless an output path is specified. Open `report.html` in a browser to view an HTML report.
|
|
204
81
|
|
|
205
|
-
|
|
206
|
-
Dev/Projects/ ███░░░░░░░ 8
|
|
207
|
-
|
|
208
|
-
Completed in 234ms
|
|
209
|
-
```
|
|
82
|
+
|
|
210
83
|
|
|
211
84
|
## Configuration
|
|
212
85
|
|
|
213
|
-
|
|
86
|
+
For persistent scan settings, create `.deadlinksrc.json` in the vault root:
|
|
214
87
|
|
|
215
88
|
```json
|
|
216
89
|
{
|
|
217
90
|
"ignore": ["**/Templates/**", "**/.trash/**"],
|
|
218
|
-
"ignoreFolders": ["Films", "
|
|
91
|
+
"ignoreFolders": ["Films", "Diary", "Books"],
|
|
219
92
|
"checkAttachments": false,
|
|
220
|
-
"
|
|
221
|
-
"debug": false,
|
|
222
|
-
"fix": false
|
|
93
|
+
"debug": false
|
|
223
94
|
}
|
|
224
95
|
```
|
|
225
96
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
### Text (default)
|
|
229
|
-
Colorful terminal output with stats, broken links, and orphan notes grouped by folder.
|
|
230
|
-
|
|
231
|
-
### JSON
|
|
232
|
-
Machine-readable format for automation and scripting.
|
|
233
|
-
|
|
234
|
-
### Markdown
|
|
235
|
-
Human-readable report with sections for broken links and orphan notes.
|
|
236
|
-
|
|
237
|
-
### CSV
|
|
238
|
-
Tabular format compatible with Excel, Google Sheets, and data analysis tools.
|
|
239
|
-
|
|
240
|
-
### HTML
|
|
241
|
-
Beautiful interactive dashboard with:
|
|
242
|
-
- Live search and filtering
|
|
243
|
-
- Stats cards with metrics
|
|
244
|
-
- Sortable tables
|
|
245
|
-
- Most connected notes preview
|
|
246
|
-
- Responsive design
|
|
247
|
-
|
|
248
|
-
### Mermaid
|
|
249
|
-
Graph visualization in Mermaid syntax. Render in:
|
|
250
|
-
- GitHub README files
|
|
251
|
-
- Obsidian notes
|
|
252
|
-
- Notion docs
|
|
253
|
-
- Online editors (mermaid.live)
|
|
97
|
+
Command-line options override the corresponding configuration values.
|
|
254
98
|
|
|
255
|
-
|
|
256
|
-
Professional graph format for advanced visualization tools:
|
|
257
|
-
- Graphviz CLI: `dot -Tpng graph.dot -o graph.png`
|
|
258
|
-
- Online: webgraphviz.com
|
|
99
|
+
## Links detected
|
|
259
100
|
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
Example output:
|
|
269
|
-
```
|
|
270
|
-
💡 Suggestions:
|
|
271
|
-
MyNote → MyNotes (95%)
|
|
272
|
-
ProjectXY → ProjectXYZ (87%)
|
|
273
|
-
Article2 → Article1 (72%)
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
## CI/CD
|
|
277
|
-
|
|
278
|
-
Exit code is `0` if no issues found, `1` if issues exist. Perfect for CI pipelines.
|
|
279
|
-
|
|
280
|
-
```bash
|
|
281
|
-
# GitHub Actions
|
|
282
|
-
- run: npx dead-links scan --vault . --format json > report.json
|
|
283
|
-
|
|
284
|
-
# Fail pipeline if broken links exist
|
|
285
|
-
- run: npx dead-links scan --vault . --quiet && exit 1 || true
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
## Links Detected
|
|
289
|
-
|
|
290
|
-
- `[[Note]]` - Wiki links
|
|
291
|
-
- `[[Note|Alias]]` - Wiki links with alias
|
|
292
|
-
- `[[Note#Section]]` - Wiki links with heading
|
|
293
|
-
- `[[Note#^blockid]]` - Wiki links with block reference
|
|
294
|
-
- `![[image.png]]` - Embeds
|
|
295
|
-
- `[text](file.md)` - Markdown links
|
|
101
|
+
- `[[Note]]` — Obsidian wiki links
|
|
102
|
+
- `[[Note|Alias]]` — wiki links with aliases
|
|
103
|
+
- `[[Note#Section]]` — links to headings
|
|
104
|
+
- `[[Note#^blockid]]` — links to blocks
|
|
105
|
+
- `![[image.png]]` — embedded attachments
|
|
106
|
+
- `[text](file.md)` — Markdown links
|
|
296
107
|
|
|
297
108
|
## License
|
|
298
|
-
|
|
109
|
+
|
|
110
|
+
[MIT](LICENSE)
|