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:

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):

# System Report


Here is a report of the current system status.

### Disk Usage


The current disk usage is:

<!-- inscribe -->

```sh
df -h / | tail -n 1
```

### Python Output


And here is a list generated by Python:

<!-- inscribe -->

```python
for i in range(3):
    print(f"- Item number {i+1}")
```

2. Run Inscribe:

inscribe example.md -o README.md

3. Check the result (README.md):

# 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)

# 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.

The current date is <!-- inscribe -->`sh date -u +%Y-%m-%d`.

After processing, this becomes:

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.

<!-- inscribe python command="python3.11 -u" -->

<!-- inscribe my-lisp command="sbcl --script" -->


# Using a specific Python version


<!-- inscribe -->

```python
import sys
print(sys.version)
```

# Using a custom language runner


<!-- inscribe -->

```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.