Hercule – Markdown Transclusion Tool

Write large markdown documents, including API Blueprints, while keeping things DRY (don't repeat yourself).

hercule src/document.md -o document.md

Hercule is a command-line tool and library for transcluding markdown documents, including API documentation written in API Blueprint format. With Hercule you can easily break complex documents into smaller logical documents, preventing repetition and improving consistency using transclusion links :[abstract](src/abstract.md).

---

Hercule is used by Adslot to help document our APIs in API Blueprint more efficiently and more accurately. We also use Apiary to distribute our API documentation and DREDD (a tool by Apiary) to validate the documentation against implementation.

---

Installation

Node.js and NPM is required.

$ npm install -g hercule

Use as a command-line utility:

hercule src/document.md -o document.md

Or use as a library:

var hercule = require('hercule');

hercule.transcludeString("# Title\n\n:[abstract](abstract.md)", function(output) {
  return console.log(output);
});

Basic use: file transclusion

Hercule extends the Markdown inline link syntax with a leading colon (:) to denote the link should transcluded.

This is an :[example link](foo.md).

Output from hercule examples/basic/main.md:

This is an example transclusion.

Extending the standard Markdown link syntax means that most other markdown parsers will treat them as normal links. For example, Github handles transclusion links in this manner.

Basic use: remote file (http) transclusion

Hercule is able to transclude HTTP references also. This done by simply providing the URL as the link.

Jackdaws love my :[size](https://gist.githubusercontent.com/jamesramsay/e869c0164a187cc756d4/raw/5e6052f67b6bf87c6862e3e17e1a646cf31cbe16/size.md) sphinx of quartz.

Output from hercule test/fixtures/test-http-live/jackdaw.md:

Jackdaws love my big sphinx of quartz.

Advanced use: placeholders and references

As well as basic file transclusion, Hercule supports placeholders and references. Placeholders and references may be useful for increasing the 'dryness' of your source documents.

Example placeholder link in examples/advanced/foo.md:

is an :[example placeholder](bar)

In this example bar is being used as a placeholder link. When transcluding foo.md, the placeholder can be targeted by a reference file or string.

This document :[example link with string reference](foo.md bar:"example foobar!")

Output from hercule examples/advanced/main.md:

This document is an example foobar!

References are passed down to any nested transclusion links.

Advanced use: default placeholders

Sometimes a file might be used in multiple contexts, some contexts requiring references and others not. Default placeholders help handle this situation more conveniently.

The following example uses Apiary's Markdown Syntax for Object Notation (MSON).

## Properties

- id: 1 (number, required)
- name: Cucumber (string, required)
- description: Essential for tzatziki (string, :[is required](required || "optional"))

Output from hercule examples/default/main.md without reference required:

## Properties

- id: 1 (number, required)
- name: Cucumber (string, required)
- description: Essential for tzatziki (string, optional)

Output from hercule examples/default/main-override.md with reference required:

## Properties

- id: 1 (number, required)
- name: Cucumber (string, required)
- description: Essential for tzatziki (string, required)

Whitespace sensitivity

Leading whitespace is significant in Markdown. Hercule preserves whitespace at the beginning of each line.

Binary sort example:

  :[](snippet.c)

Each line of snippet.c will be indented with the whitespace preceding it.

---

Acknowledgments

Special thanks:

• @zdne for your feedback and ideas, particularly on syntax
• @MichaelHirn for contributions including the default link behaviour

Related projects:

• Grunt Hercule: a Grunt task that wraps hercule