# Inscribe
[](https://crates.io/crates/inscribe)
[](https://github.com/your-username/inscribe)
**Inscribe brings your markdown documents to life by executing embedded code blocks and embedding their output.**
It's a powerful command-line preprocessor that lets you create dynamic, self-updating documentation, tutorials, and reports.
---
## What is Inscribe?
Inscribe is a tool for literate programming and dynamic document generation. It parses a markdown file, looks for specially marked code fences, executes the code within them, and *inscribes* the standard output of the code back into the document.
This means your code examples, command outputs, and generated values are always up-to-date, turning static files into living documents.
### Key Features
- **Execute Code Fences:** Run code from various languages directly within your markdown.
- **Multi-Language Support:** Comes with built-in runners for Python, JavaScript/Node, Ruby, and Shell (`bash`, `sh`).
- **Customizable Runners:** Easily define custom commands for any language (e.g., use `python3` instead of `python`, or add a new language).
- **Inline Code Execution:** Inscribe can also run and replace short, inline code snippets.
- **File Watching:** Automatically reprocess your document when the source file changes.
- **Post-Processing Hooks:** Run any command (like a static site generator) after a file is successfully processed.
- **Standard I/O:** Works seamlessly with `stdin` and `stdout` for easy integration into Unix pipelines.
## Getting Started
### Installation
Ensure you have the Rust toolchain installed. You can then install `inscribe` directly from Crates.io:
```bash
cargo install inscribe
```
## Usage
### Basic Example
To mark a code block for execution, precede it with an HTML comment: `<!-- inscribe -->`.
**1. Create a markdown file (`example.md`):**
````markdown
# System Report
Here is a report of the current system status.
### Disk Usage
The current disk usage is:
```sh
### Python Output
And here is a list generated by Python:
```python
for i in range(3):
print(f"- Item number {i+1}")
```
````
**2. Run Inscribe:**
```bash
inscribe example.md -o README.md
```
**3. Check the result (`README.md`):**
````markdown
# System Report
Here is a report of the current system status.
### Disk Usage
The current disk usage is:
/dev/vda1 100G 25G 75G 26% /
### Python Output
And here is a list generated by Python:
- Item number 1
- Item number 2
- Item number 3
````
### Command-Line Interface (CLI)
```bash
# Process a file and print to stdout
inscribe input.md
# Process a file and write to an output file
inscribe input.md --output output.md
inscribe input.md -o output.md
# Read from stdin and write to stdout
cat input.md | inscribe > output.md
# Watch a file for changes and reprocess automatically
inscribe input.md -o output.md --watch
# Run a command after successful processing
# (Placeholders {{input}} and {{output}} are available)
inscribe docs.md -o book.html --on-finish "pandoc {{output}} -o final.pdf"
```
## Advanced Usage
### Inline Code Execution
For short, single-line outputs, you can use inline code blocks. Inscribe will use the language of the most recent fenced code block.
````markdown
The current date is <!-- inscribe -->`sh date -u +%Y-%m-%d`.
````
After processing, this becomes:
```markdown
The current date is 2023-10-27.
```
### Customizing Language Runners
You can override the default command for a language or define a new one for the entire document. This is useful for specifying interpreter versions or custom runtimes.
The syntax is a special HTML comment: `<!-- inscribe <language> command="..." -->`. These definitions are invisible in the final output.
````markdown
# Using a specific Python version
```python
import sys
print(sys.version)
```
# Using a custom language runner
```my-lisp
(format t "Hello from Lisp!~%")
```
````
## Supported Languages
`inscribe` comes with the following runners configured by default:
- `python`
- `bash`
- `sh`
- `javascript` / `node`
- `ruby`
You can add any other language with the custom runner syntax shown above.
## Contributing
Contributions are welcome! Feel free to open an issue for bug reports or feature requests, or submit a pull request.
## License
This project is licensed under either of
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
at your option.