0
# Command Line Interface
1

2
Complete command-line interface for project creation, notebook conversion, and document generation across multiple output formats. The CLI provides standalone tools for MyST-NB functionality outside of Sphinx.
3

4
## Capabilities
5

6
### Project Creation
7

8
Command-line tool for creating new MyST-NB projects with proper structure and configuration.
9

10
```python { .api }
11
def quickstart(args: list[str] | None = None) -> None:
12
    """
13
    Create a new MyST-NB project with basic structure and configuration.
14
    
15
    Parameters:
16
    - args: Optional command-line arguments list
17
    
18
    Creates directory structure, configuration files, and example notebooks.
19
    """
20
```
21

22
**CLI Entry Point**: `mystnb-quickstart`
23

24
### Notebook Conversion
25

26
Convert MyST markdown files to Jupyter notebook format.
27

28
```python { .api }
29
def md_to_nb(args: list[str] | None = None) -> None:
30
    """
31
    Convert MyST markdown to Jupyter notebook format.
32
    
33
    Parameters:
34
    - args: Optional command-line arguments list
35
    
36
    Converts .md files with notebook content to .ipynb format
37
    while preserving cell structure and metadata.
38
    """
39
```
40

41
**CLI Entry Point**: `mystnb-to-jupyter`
42

43
## Docutils Output Commands
44

45
Direct document generation using docutils backend for various output formats.
46

47
### HTML Output
48

49
```python { .api }
50
def cli_html(argv: list[str] | None = None) -> None:
51
    """
52
    Generate HTML output from notebook using docutils.
53
    
54
    Parameters:
55
    - argv: Command-line arguments for HTML generation
56
    
57
    Processes notebook and generates standalone HTML document.
58
    """
59
```
60

61
**CLI Entry Point**: `mystnb-docutils-html`
62

63
### HTML5 Output
64

65
```python { .api }
66
def cli_html5(argv: list[str] | None = None):
67
    """
68
    Generate HTML5 output from notebook using docutils.
69
    
70
    Parameters:
71
    - argv: Command-line arguments for HTML5 generation
72
    
73
    Processes notebook and generates HTML5 document with modern features.
74
    """
75
```
76

77
**CLI Entry Point**: `mystnb-docutils-html5`
78

79
### LaTeX Output
80

81
```python { .api }
82
def cli_latex(argv: list[str] | None = None):
83
    """
84
    Generate LaTeX output from notebook using docutils.
85
    
86
    Parameters:
87
    - argv: Command-line arguments for LaTeX generation
88
    
89
    Processes notebook and generates LaTeX document suitable for PDF compilation.
90
    """
91
```
92

93
**CLI Entry Point**: `mystnb-docutils-latex`
94

95
### XML Output
96

97
```python { .api }
98
def cli_xml(argv: list[str] | None = None):
99
    """
100
    Generate XML output from notebook using docutils.
101
    
102
    Parameters:
103
    - argv: Command-line arguments for XML generation
104
    
105
    Processes notebook and generates structured XML document.
106
    """
107
```
108

109
**CLI Entry Point**: `mystnb-docutils-xml`
110

111
### Pseudo-XML Output
112

113
```python { .api }
114
def cli_pseudoxml(argv: list[str] | None = None):
115
    """
116
    Generate pseudo-XML output from notebook using docutils.
117
    
118
    Parameters:
119
    - argv: Command-line arguments for pseudo-XML generation
120
    
121
    Processes notebook and generates pseudo-XML for debugging document structure.
122
    """
123
```
124

125
**CLI Entry Point**: `mystnb-docutils-pseudoxml`
126

127
## Usage Examples
128

129
### Project Quickstart
130

131
```bash
132
# Create a new MyST-NB project
133
mystnb-quickstart
134

135
# Interactive prompts will ask for:
136
# - Project name
137
# - Author name  
138
# - Initial configuration options
139
# - Example notebook creation
140
```
141

142
This creates a directory structure like:
143
```
144
my-project/
145
├── conf.py
146
├── index.md
147
├── notebooks/
148
│   └── example.ipynb
149
└── _build/
150
```
151

152
### Notebook Conversion
153

154
```bash
155
# Convert MyST markdown to notebook
156
mystnb-to-jupyter my-notebook.md my-notebook.ipynb
157

158
# Convert with execution
159
mystnb-to-jupyter --execute my-notebook.md my-notebook.ipynb
160

161
# Convert multiple files
162
mystnb-to-jupyter notebooks/*.md --output-dir converted/
163
```
164

165
### HTML Generation
166

167
```bash
168
# Generate HTML from notebook
169
mystnb-docutils-html notebook.ipynb output.html
170

171
# Generate with custom CSS
172
mystnb-docutils-html --stylesheet-path custom.css notebook.ipynb output.html
173

174
# Generate HTML5 with modern features
175
mystnb-docutils-html5 --math-output=mathjax notebook.ipynb output.html
176
```
177

178
### LaTeX/PDF Generation
179

180
```bash
181
# Generate LaTeX
182
mystnb-docutils-latex notebook.ipynb output.tex
183

184
# Generate with custom document class
185
mystnb-docutils-latex --documentclass=article notebook.ipynb output.tex
186

187
# Process with pdflatex
188
mystnb-docutils-latex notebook.ipynb output.tex && pdflatex output.tex
189
```
190

191
### XML and Debug Output
192

193
```bash
194
# Generate structured XML
195
mystnb-docutils-xml notebook.ipynb output.xml
196

197
# Generate pseudo-XML for debugging
198
mystnb-docutils-pseudoxml notebook.ipynb debug.xml
199
```
200

201
### Batch Processing
202

203
```bash
204
# Process multiple notebooks to HTML
205
for notebook in notebooks/*.ipynb; do
206
    mystnb-docutils-html "$notebook" "html/$(basename "$notebook" .ipynb).html"
207
done
208

209
# Convert all markdown notebooks
210
find . -name "*.md" -type f -exec mystnb-to-jupyter {} {}.ipynb \;
211
```
212

213
### Configuration Options
214

215
Most CLI commands accept standard docutils options:
216

217
```bash
218
# Common options across commands
219
--config-file CONFIG_FILE     # Use custom configuration
220
--output-encoding ENCODING    # Set output encoding
221
--language LANGUAGE           # Set document language
222
--title TITLE                 # Set document title
223
--stylesheet-path PATH        # Custom stylesheet
224
--template TEMPLATE           # Custom template
225

226
# MyST-NB specific options
227
--execution-mode MODE         # Set execution mode
228
--execution-timeout SECONDS   # Set execution timeout
229
--remove-code-source          # Hide source code
230
--remove-code-outputs         # Hide outputs
231
```
232

233
### Integration with Build Systems
234

235
```bash
236
# In Makefile
237
html:
238
    find notebooks/ -name "*.ipynb" -exec mystnb-docutils-html {} docs/{}.html \;
239

240
# In GitHub Actions
241
- name: Generate documentation
242
  run: |
243
    for nb in notebooks/*.ipynb; do
244
      mystnb-docutils-html "$nb" "docs/$(basename "$nb" .ipynb).html"
245
    done
246
```
247

248
### Error Handling
249

250
CLI commands provide detailed error reporting:
251

252
```bash
253
# Check syntax and execution
254
mystnb-to-jupyter --validate notebook.md
255

256
# Generate with error reporting
257
mystnb-docutils-html --traceback notebook.ipynb output.html
258
```
259

260
The CLI tools integrate with MyST-NB's configuration system and provide the same functionality as the Sphinx extension in standalone form, making them suitable for custom build pipelines and automated processing workflows.