0
# CLI Tools
1

2
Command-line utilities for MyST document processing, including HTML, LaTeX, XML output generation, heading anchor extraction, and inventory management.
3

4
## Capabilities
5

6
### Anchor Extraction
7

8
Extract and display heading anchors from MyST documents, useful for link validation and cross-reference management.
9

10
```python { .api }
11
def print_anchors(args=None) -> None:
12
    """
13
    CLI command to print heading anchors from MyST files.
14
    
15
    Scans MyST documents and extracts all heading anchors,
16
    displaying them in a format suitable for cross-reference validation.
17
    
18
    Args:
19
        args: Command-line arguments (optional, uses sys.argv if None)
20
    """
21
```
22

23
Command-line usage:
24

25
```bash
26
# Extract anchors from single file
27
myst-anchors document.md
28

29
# Extract anchors from multiple files
30
myst-anchors docs/*.md
31

32
# Output format: filename:line:anchor
33
# example.md:5:section-header
34
# example.md:12:subsection-title
35
```
36

37
Usage example:
38

39
```python
40
from myst_parser.cli import print_anchors
41
import sys
42

43
# Programmatic usage
44
sys.argv = ['myst-anchors', 'example.md']
45
print_anchors()
46

47
# Or with explicit args
48
print_anchors(['example.md', '--format=json'])
49
```
50

51
### Inventory Management
52

53
Comprehensive inventory management for Sphinx cross-reference integration, supporting loading, conversion, and manipulation of inventory data.
54

55
```python { .api }
56
def inventory_cli(inputs: None | list[str] = None) -> None:
57
    """
58
    Command line interface for fetching and parsing an inventory.
59
    
60
    Provides functionality for loading, parsing, and filtering Sphinx
61
    inventory files for cross-reference integration.
62
    
63
    Args:
64
        inputs: Optional list of command-line arguments
65
    """
66
```
67

68
Command-line usage:
69

70
```bash
71
# Load and display inventory
72
myst-inv load https://docs.python.org/3/objects.inv
73

74
# Convert inventory format
75
myst-inv convert --input objects.inv --output inventory.json
76

77
# Validate inventory
78
myst-inv validate objects.inv
79

80
# Search inventory
81
myst-inv search --query "dict" objects.inv
82
```
83

84
Usage example:
85

86
```python
87
from myst_parser.inventory import inventory_cli
88
import sys
89

90
# Load inventory programmatically
91
sys.argv = ['myst-inv', 'load', 'objects.inv']
92
inventory_cli()
93

94
# Convert inventory format
95
sys.argv = ['myst-inv', 'convert', '--format', 'json', 'objects.inv']
96
inventory_cli()
97
```
98

99
### Docutils Output Formats
100

101
Comprehensive set of docutils-based output generators supporting multiple formats including HTML, LaTeX, XML, and pseudoXML.
102

103
```python { .api }
104
def cli_html(argv: list[str] | None = None) -> None:
105
    """
106
    Cmdline entrypoint for converting MyST to HTML.
107
    
108
    Args:
109
        argv: Command-line arguments list
110
    """
111

112
def cli_html5(argv: list[str] | None = None) -> None:
113
    """
114
    Cmdline entrypoint for converting MyST to HTML5.
115
    
116
    Args:
117
        argv: Command-line arguments list
118
    """
119

120
def cli_html5_demo(argv: list[str] | None = None) -> None:
121
    """
122
    Cmdline entrypoint for converting MyST to simple HTML5 demonstrations.
123
    
124
    This is a special case of the HTML5 writer that only outputs
125
    the body of the document.
126
    
127
    Args:
128
        argv: Command-line arguments list
129
    """
130

131
def cli_latex(argv: list[str] | None = None) -> None:
132
    """
133
    Cmdline entrypoint for converting MyST to LaTeX.
134
    
135
    Args:
136
        argv: Command-line arguments list
137
    """
138

139
def cli_xml(argv: list[str] | None = None) -> None:
140
    """
141
    Cmdline entrypoint for converting MyST to XML.
142
    
143
    Args:
144
        argv: Command-line arguments list
145
    """
146

147
def cli_pseudoxml(argv: list[str] | None = None) -> None:
148
    """
149
    Cmdline entrypoint for converting MyST to pseudoXML.
150
    
151
    Args:
152
        argv: Command-line arguments list
153
    """
154
```
155

156
Command-line usage:
157

158
```bash
159
# Generate HTML output
160
myst-docutils-html input.md output.html
161

162
# Generate HTML5 with modern features
163
myst-docutils-html5 input.md output.html
164

165
# Generate demo HTML with styling
166
myst-docutils-demo input.md output.html
167

168
# Generate LaTeX output
169
myst-docutils-latex input.md output.tex
170

171
# Generate XML for processing
172
myst-docutils-xml input.md output.xml
173

174
# Generate pseudoXML for debugging
175
myst-docutils-pseudoxml input.md output.xml
176
```
177

178
Usage example:
179

180
```python
181
from myst_parser.parsers.docutils_ import cli_html, cli_latex
182

183
# Generate HTML output
184
cli_html(['document.md', 'output.html'])
185

186
# Generate LaTeX output with custom settings
187
cli_latex([
188
    'document.md', 
189
    'output.tex',
190
    '--documentclass=article',
191
    '--use-latex-citations'
192
])
193
```
194

195
### Advanced Output Options
196

197
All CLI tools support advanced configuration options for customizing output generation and processing behavior.
198

199
```bash
200
# Common options for all output formats:
201

202
# Configuration file
203
--config config.json
204

205
# MyST extensions
206
--myst-enable-extensions=tasklist,deflist,substitution
207

208
# Heading anchors
209
--myst-heading-anchors=3
210

211
# Math rendering
212
--myst-dmath-double-inline
213

214
# Footnote handling
215
--myst-footnote-transition
216
--myst-footnote-sort
217

218
# HTML-specific options (myst-docutils-html, myst-docutils-html5)
219
--stylesheet-path=custom.css
220
--template=custom-template.html
221
--embed-stylesheet
222

223
# LaTeX-specific options (myst-docutils-latex)
224
--documentclass=article
225
--use-latex-citations
226
--latex-preamble=preamble.tex
227

228
# XML-specific options (myst-docutils-xml)
229
--xml-declaration
230
--encoding=utf-8
231
```
232

233
Usage examples:
234

235
```bash
236
# HTML with custom styling and extensions
237
myst-docutils-html5 \
238
    --myst-enable-extensions=tasklist,deflist,substitution \
239
    --myst-heading-anchors=3 \
240
    --stylesheet-path=docs.css \
241
    --embed-stylesheet \
242
    input.md output.html
243

244
# LaTeX with academic formatting
245
myst-docutils-latex \
246
    --myst-enable-extensions=amsmath,dollarmath \
247
    --documentclass=article \
248
    --use-latex-citations \
249
    --latex-preamble=preamble.tex \
250
    paper.md paper.tex
251

252
# XML for further processing
253
myst-docutils-xml \
254
    --myst-enable-extensions=substitution \
255
    --xml-declaration \
256
    --encoding=utf-8 \
257
    document.md document.xml
258
```
259

260
### Batch Processing
261

262
All CLI tools support batch processing of multiple files and directories:
263

264
```bash
265
# Process multiple files
266
myst-docutils-html *.md
267

268
# Process directory recursively
269
myst-docutils-html5 --recursive docs/ output/
270

271
# Process with pattern matching
272
myst-docutils-latex docs/**/*.md output/
273
```
274

275
### Configuration Files
276

277
CLI tools support configuration files for consistent processing across projects:
278

279
```json
280
// myst-config.json
281
{
282
    "myst_enable_extensions": [
283
        "tasklist",
284
        "deflist", 
285
        "substitution",
286
        "colon_fence"
287
    ],
288
    "myst_heading_anchors": 3,
289
    "myst_footnote_transition": true,
290
    "myst_dmath_double_inline": true,
291
    "html_theme": "alabaster",
292
    "latex_documentclass": "article"
293
}
294
```
295

296
```bash
297
# Use configuration file
298
myst-docutils-html5 --config myst-config.json input.md output.html
299
```
300

301
### Output Validation and Debugging
302

303
Tools for validating and debugging MyST document processing:
304

305
```bash
306
# Validate MyST syntax
307
myst-docutils-pseudoxml document.md > debug.xml
308

309
# Check for parsing warnings
310
myst-docutils-html document.md output.html --verbose
311

312
# Validate cross-references
313
myst-anchors document.md --validate-refs
314

315
# Debug inventory loading
316
myst-inv validate --verbose objects.inv
317
```
318

319
## Command Reference
320

321
Complete list of available CLI commands:
322

323
| Command | Purpose | Module Path |
324
|---------|---------|-------------|
325
| `myst-anchors` | Extract heading anchors | `myst_parser.cli:print_anchors` |
326
| `myst-inv` | Inventory management | `myst_parser.inventory:inventory_cli` |
327
| `myst-docutils-html` | HTML output | `myst_parser.parsers.docutils_:cli_html` |
328
| `myst-docutils-html5` | HTML5 output | `myst_parser.parsers.docutils_:cli_html5` |
329
| `myst-docutils-demo` | HTML5 demo | `myst_parser.parsers.docutils_:cli_html5_demo` |
330
| `myst-docutils-latex` | LaTeX output | `myst_parser.parsers.docutils_:cli_latex` |
331
| `myst-docutils-xml` | XML output | `myst_parser.parsers.docutils_:cli_xml` |
332
| `myst-docutils-pseudoxml` | PseudoXML output | `myst_parser.parsers.docutils_:cli_pseudoxml` |
333
334
## Types
335

336
CLI-related type definitions:
337

338
```python { .api }
339
# CLI function signature
340
CLIFunction = Callable[[list[str] | None], None]
341

342
# Configuration types
343
ConfigDict = dict[str, any]
344
OutputFormat = Literal["html", "html5", "latex", "xml", "pseudoxml"]
345

346
# Command result types
347
class CLIResult:
348
    """Result from CLI command execution."""
349
    success: bool
350
    output: str
351
    errors: list[str]
352
```