Repository files navigation

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 keeptrack of line numbers
• Dedent included snippets

The filter recognizes code blocks with theinclude attribute present. Itswaps the content of the code block with contents from a file.

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

There is support for delimitedsnippets. Use a line comment ofwhatever kind you want, and enclose the snippet betweenstart snippet <name> andend snippet <name>.

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

Or why not some C code:

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

NOTE: There can only be whitespace and a newlineafter thesnippet 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}```

If you want to include a specific range of lines, usestartLine andendLine:

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

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

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

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

If you include thenumberLines class in your code block, and useinclude,thestartFrom attribute will be added with respect to the included code'slocation in the source file.

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

It is possible to add hyperlinks to the original source code file specified in theinclude attribute by adding the.includeLink class in your code block.

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

A base url will be appended to all relative paths specified in theinclude attribute of eachCodeBlock . It does not affect paths beginning withfile: ,C:,\,/,.... This can be donetwo option:

Specify a base key along with the base url as the attribute inthe YAML header:

    ---    title:    All About Wonderland    author:   Alice    date:     November 2020    base:     http://localhost:8000/    ---

Add the base as a metavalue -M base=<base url> or --metavalue base=<base url> in the command line whencalling pandoc.

pandoc --filter pandoc-include-code -M base=http://localhost:8000/  in.md -o out.html

NOTE: If the base url is specified in the metadata block, thenby specifying a different base in the command line, it will overridethe original base.

Both of these options will add a hyperlink to the filepath definedin theinclude attribute linking tohttp://localhost:8000/source/sample.hs:

Adding a base attribute in the metadata block or the command linewill affect all relative links in theCodeBlocks. To add an alternative base for aspecific link, add the base as an attributebase=https.... totheCodeBlock:

```{.haskell .includeLink include=source/sample.hs snippet=animals base=<path>}```

This adds a hyperlink to the filepath specified in theinclude attribute linking to../source/sample.hs :

• The blog postAutomating the Build of Your Technical Presentationshows practical examples of how to use this filter.

Executables for Linux and macOS are available in theReleasespage.

You can useHomebrew to install this filter:

brew install pandoc-include-code

If you'd rather install usingcabal orstack, you can use the followingcommand:

cabal install pandoc-include-code

The package isavailable at Hackage.

Requirements:

• Cabal orStack, either works.

To install from sources, run:

git clone git@github.com:owickstrom/pandoc-include-code.gitcd pandoc-include-codecabal configurecabal install

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

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

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

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

importText.Pandoc (Format (..),Pandoc)importText.Pandoc.Walk (walkM)importText.Pandoc.Filter.IncludeCode (includeCode)includeCodeTransform::Pandoc->IOPandocincludeCodeTransform= walkM (includeCode (Just (Format"html5")))includeCodePandocCompiler::Compiler (ItemString)includeCodePandocCompiler=  pandocCompilerWithTransformM    defaultHakyllReaderOptions    defaultHakyllWriterOptions    (unsafeCompiler. includeCodeTransform)

You can now useincludeCodePandocCompiler instead of the defaultpandocCompiler in your Hakyll rules:

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

CHANGELOG.md

Mozilla Public License Version 2.0