pandoc-include-code alternatives and similar packages
Based on the "Documentation" category.
Alternatively, view pandoc-include-code alternatives based on common mentions on social networks and blogs.
-
dash-haskell
dash docset builder for Haskell packages and cabal project dependencies -
archiver
Background daemon which archives a list of URLs to the Internet Archive, archive.is, and other services -
hoogle-index
Easily generate Hoogle indices for installed packages -
docidx
Create an HTML index of your installed Haskell packages. -
docstrings
document haskell definitions for access in the repl -
haddock-library
Library exposing some functionality of Haddock.
Build time-series-based applications quickly and at scale.
Do you think we are missing an alternative of pandoc-include-code or a related project?
README
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.
```{include=docs/MyFile.hs startLine=35 endLine=80 .numberLines}
```
Adding Direct Links
It is possible to add hyperlinks to the original source code file specified in the include
attribute by adding the .includeLink
class in your code block.
```{include=docs/MyFile.hs .includeLink}
```
Adding Base url for all CodeBlock links
A base url will be appended to all relative paths specified in the
include
attribute of each CodeBlock
. It does not affect paths beginning with file:
, C:
, \
, /
,.... This can be done
two option:
Option 1: YAML
Specify a base key along with the base url as the attribute in the YAML header:
---
title: All About Wonderland
author: Alice
date: November 2020
base: http://localhost:8000/
---
Option 2: Command Line
Add the base as a metavalue -M base=<base url>
or
--metavalue base=<base url>
in the command line when
calling 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, then by specifying a different base in the command line, it will override the original base.
Both of these options will add a hyperlink to the filepath defined
in the include
attribute linking to
http://localhost:8000/source/sample.hs
:
Overriding a specified base url
Adding a base attribute in the metadata block or the command line
will affect all relative links in the CodeBlocks
. To add an alternative base for a
specific link, add the base as an attribute base=https....
to
theCodeBlock
:
```{.haskell .includeLink include=source/sample.hs snippet=animals base=<path>}
This adds a hyperlink to the filepath specified in the
`include` attribute linking to `../source/sample.hs` :
### More Usage Examples
* The blog post [Automating the Build of Your Technical Presentation](https://wickstrom.tech/programming/2017/09/24/automating-the-build-of-your-technical-presentation.html)
shows practical examples of how to use this filter.
## Install
Executables for Linux and macOS are available in the [Releases
page](https://github.com/owickstrom/pandoc-include-code/releases).
### From Homebrew
You can use [Homebrew](https://brew.sh) to install this filter:
```bash
brew install pandoc-include-code
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 [email protected]: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](CHANGELOG.md)
License
[Mozilla Public License Version 2.0](LICENSE)
*Note that all licence references and agreements mentioned in the pandoc-include-code README section above
are relevant to that project's source code only.