snips

Keep your code snippets in sync with your source files. Effortlessly.

snips is a command-line tool that prevents your documentation from becoming stale. It works by creating a direct link between your source code and your Markdown files, ensuring your code examples are always up-to-date.

How It Works

snips uses two simple markers to work its magic:

1. In your source code, you define a snippet with special comments:

   // In examples/example.rs
   pub fn example() {
       // snips-start: main_feature
       println!("This is the code I want in my docs!");
       // snips-end: main_feature
   }
   

2. In your Markdown file, you reference that snippet using an HTML comment:

<!-- snips: examples/example.rs#main_feature -->
```rust
println!("This is the code I want in my docs!");
```

Run snips process, and the tool will inject the source code, automatically handling indentation and language detection.

Features

• Named Snippets: Pull specific blocks of code from any source file.
• Whole-File Insertion: Embed an entire source file with a simple marker (<!-- snips: path/to/file.rs -->).
• CI/CD Friendly: The snips check command fails if your docs are out of sync, making it perfect for CI pipelines.
• Language Agnostic: Works with any programming language that supports comments.
• Smart Language Detection: Automatically detects programming languages using the official GitHub Linguist language specification, providing accurate CodeMirror syntax highlighting modes.

Community

Want to contribute? Have ideas or feature requests? Come tell us about it on Discord.

Installation

cargo install snips

Commands

• snips render <FILES>...

  • Processes files and writes changes directly to disk.

• snips check <FILES>...

  • Checks if files are in sync. Exits with a non-zero status code if changes are needed.

• snips diff <FILES>...

  • Shows a colored diff of pending changes without modifying any files.

Related Projects

snips uses the languages library for programming language detection. This library provides access to GitHub's Linguist language specification, ensuring accurate language identification and CodeMirror mode selection for syntax highlighting in your documentation.