A Pandoc filter for including code from source files
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
filter Separate library and add basic test Sep 16, 2017
src/Text/Pandoc/Filter Add support for line numbers and automatic startFrom Feb 3, 2018
test Add support for line numbers and automatic startFrom Feb 3, 2018
.gitignore
.travis.yml Add travis config with release build Nov 4, 2017
CHANGELOG.md Update readme Feb 4, 2018
LICENSE Initial commit Feb 20, 2017
README.md Use filter as in library in Hakyll instructions Sep 9, 2018
Setup.hs Replace weird copy-pasted Setup script with default Dec 29, 2017
pandoc-include-code.cabal
stack.yaml Use new Pandoc 1.19 Feb 21, 2017

README.md

pandoc-include-code

A Pandoc filter for including code from source files.

You get to:

  • Keep your examples and documentation compiled and in sync
  • Include small snippets from larger source files without needing to keep track of line numbers
  • Dedent included snippets

Usage

The filter recognizes code blocks with the include attribute present. It swaps the content of the code block with contents from a file.

Including Files

The simplest way to use this filter is to include an entire file:

```{include=docs/MyFile.hs}
```

You can still use other attributes, and classes, to control the code blocks:

```{.purescript include=docs/MyFile.purs}
```

Snippets

There is support for delimited snippets. Use a line comment of whatever kind you want, and enclose the snippet between start snippet <name> and end snippet <name>.

-- start snippet cool-thingy
main =
  putStrLn "I explain some cool concept in Haskell code."
-- end snippet cool-thingy

Or why not some C code:

// start snippet wow
int main() {
    printf("such performance");
}
// end snippet wow

NOTE: There can only be whitespace and a newline after the snippet name. This means that multi-line comments in C, Java, etc, will not work. Only single-line comments will.

Then, in your code block, specify the snippet name:

```{include=docs/MyFile.hs snippet=cool-thingy}
```

Ranges

If you want to include a specific range of lines, use startLine and endLine:

```{include=docs/MyFile.hs startLine=35 endLine=80}
```

Dedent

Using the dedent attribute, you can have whitespaces removed on each line, where possible (non-whitespace character will not be removed even if they occur in the dedent area).

```{include=docs/MyFile.hs dedent=4}
```

Conflicting Modes

"Snippet mode" and "range mode" cannot be used together.

Line Numbers

If you include the numberLines class in your code block, and use include, the startFrom attribute will be added with respect to the included code's location in the source file.

More Usage Examples

Install

Executables for Linux and macOS are available in the Releases page.

From Hackage

If you'd rather install using cabal or stack, you can use the following command:

cabal install pandoc-include-code

The package is available at Hackage.

Build

Requirements:

To install from sources, run:

git clone git@github.com:owickstrom/pandoc-include-code.git
cd pandoc-include-code
cabal configure
cabal install

Run

If you have installed from sources, and you have ~/.local/bin on your PATH, you can use the filter with Pandoc like so:

pandoc --filter pandoc-include-code input.md output.html

Usage with Hakyll

If you are using the Hakyll static site generator, you can use the filter by importing it as a library and using the snippet below.

Add pandoc, pandoc-types, and pandoc-include-code to your project dependencies, then define a custom Hakyll compiler using a Pandoc transform:

import Text.Pandoc (Format (..), Pandoc)
import Text.Pandoc.Walk (walkM)
import Text.Pandoc.Filter.IncludeCode (includeCode)

includeCodeTransform :: Pandoc -> IO Pandoc
includeCodeTransform = walkM (includeCode (Just (Format "html5")))

includeCodePandocCompiler :: Compiler (Item String)
includeCodePandocCompiler =
  pandocCompilerWithTransformM
    defaultHakyllReaderOptions
    defaultHakyllWriterOptions
    (unsafeCompiler . includeCodeTransform)

You can now use includeCodePandocCompiler instead of the default pandocCompiler in your Hakyll rules:

match "*.md" $ do
  route $ setExtension "html"
  compile $ includeCodePandocCompiler
    >>= loadAndApplyTemplate "templates/default.html" defaultContext
    >>= relativizeUrls

Changelog

CHANGELOG.md

License

Mozilla Public License Version 2.0