Skip to main content
The example command creates a pre-populated markdown file that demonstrates all supported features including syntax highlighting, Mermaid diagrams, tables, and formatting options.

​
Usage

markdown-os example [OUTPUT] [OPTIONS]

​
Arguments

​
OUTPUT
Path
default:"example.md"
Output path for the generated showcase markdown file.Behavior:
  • If OUTPUT is a directory, the file is created as OUTPUT/example.md
  • If OUTPUT is a file path, uses that exact path
  • Parent directories are created automatically if they don’t exist
  • Tilde (~) expansion is supported
Source: cli.py:273-276

​
Options

​
--open
bool
default:"false"
Automatically open the generated example file in the Markdown-OS editor after creation.When enabled, this flag chains the example command with open, equivalent to:
markdown-os example && markdown-os open example.md
Source: cli.py:277-281
​
--force
bool
default:"false"
Overwrite existing files without prompting for confirmation.Aliases: -f, --forceWithout this flag, if the output file exists, you’ll be prompted:
File example.md already exists. Overwrite? [y/N]:
Source: cli.py:282-287

​
Examples

markdown-os example
# Creates ./example.md in current directory

​
Terminal Output

​
Success

$ markdown-os example
Created example file: /home/user/example.md
Next step:
  markdown-os open /home/user/example.md

​
With —open Flag

$ markdown-os example --open
Created example file: /home/user/example.md
Next step:
  markdown-os open /home/user/example.md
Opening in editor...
Opening file /home/user/example.md at http://127.0.0.1:8000
INFO:     Started server process [12345]
...

​
Overwrite Prompt

$ markdown-os example
File /home/user/example.md already exists. Overwrite? [y/N]: n
Cancelled.

​
With —force Flag

$ markdown-os example --force
Created example file: /home/user/example.md
Next step:
  markdown-os open /home/user/example.md

​
Template Source

The example content is loaded from a bundled template file: 
markdown_os/templates/example_template.md
This template is included in the package distribution and demonstrates:
  • Headings (H1-H6)
  • Text formatting (bold, italic, code)
  • Lists (ordered, unordered, nested)
  • Code blocks with syntax highlighting
  • Mermaid diagrams
  • Tables
  • Blockquotes
  • Horizontal rules
  • Links and images
Source: cli.py:201-213

​
Behavior Details

​
Path Resolution

  1. Tilde expansion: ~/docs/example.md → /home/user/docs/example.md
  2. Directory detection: If path exists and is a directory, appends /example.md
  3. Absolute path: All paths are resolved to absolute before writing
Source: cli.py:184-198

​
File Writing Process

  1. Parent directory creation: mkdir -p equivalent (parents=True, exist_ok=True)
  2. Template loading: Read from package resources (UTF-8 encoding)
  3. Write operation: Save with UTF-8 encoding
  4. Success message: Print green confirmation with full resolved path
  5. Next step hint: Show suggested open command
  6. Optional open: If --open flag, chain to open_markdown_file()
Source: cli.py:301-332

​
Overwrite Protection

When the output file exists: 
if resolved_output.exists() and not force:
    overwrite = typer.confirm(
        f"File {resolved_output} already exists. Overwrite?",
        default=False,
    )
    if not overwrite:
        typer.echo("Cancelled.")
        raise typer.Exit(code=0)
Source: cli.py:303-310

​
Error Handling

$ markdown-os example
Template file is missing. Expected markdown_os/templates/example_template.md.
# Exit code: 1
Error handling source: cli.py:312-324

​
Exit Codes

CodeMeaning
0Success (file created or user cancelled)
1Error (template missing, write failure, etc.)

​
Use Cases

Quick Start

Generate an example and immediately start editing to learn the features:
markdown-os example --open

Documentation Template

Create a template for team documentation:
markdown-os example ./docs/TEMPLATE.md

Testing Features

Generate a file to test syntax highlighting and Mermaid rendering:
markdown-os example test.md --open

CI/CD Integration

Generate examples in automated scripts:
markdown-os example ./output/demo.md --force
The generated example file is a static snapshot of the template. It does not auto-update when the package is upgraded. To get the latest template, regenerate the file with --force.

Build docs developers (and LLMs) love

Get started for freeTalk to us