Snarl is a literate programming tool for Markdown documents.
- Literate programming while keeping your markdown editor happy.
- Label your code blocks for use in generating files.
- Generate files using named code blocks and verbatim content. Blocks can be assembled out-of-order.
- Include files to split a large document across multiple files.
Code blocks are defined using a modified version the standard Markdown syntax for fenced code blocks:
```[lang]=label [options]
...your code goes here...
```
Everything after the = (or +=) is stripped when weaving, leaving a standard fenced code block.
The following options are available:
--hide-- causes snarl to ignore the code block when weaving.--file-- marks the block as a file that should be generated when tangling.--replace *pattern* *substitution*-- when tangling, replace pattern with subsitution.--tag *tag*-- assign a tag to a block, which can be used to select sets of files when tangling. May be specified multiple times.--escape-html-- escape characters in the code block that would cause undesirable behavior when rendered to HTML.--verbatim-- do not process<<...>>blocks in the code block
There is alternate syntax used to append content to an existing code block:
```[lang]+=label
...your code goes here...
```
You can't set options on an appended block (it becomes part of the previously declared block).
To include content from one code block in another code block when tangling, refer to it using <<...>> markers. For example:
```=hello.c --file
<<includes>>
int main() {
<<body of main function>>
}
```
Include files with the <!-- include ... --> directive:
<!-- include *path* [--escape-html] [--verbatim] -->
The contents of the named file will be processed as if it occurred in the main document at the point of the <!-- include ... --> directive. This means you can include snarl syntax in your included files.
The following options are available:
--escape-html-- escape characters that will cause problems when rendered to HTML (such as<and&).--verbatim-- insert the content without processing it for snarl directives.
- I wrote a blog post about this tool.