Hercule – Transclusion Tool

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

Hercule is a command-line tool and library for transcluding markdown, API Blueprint, and plain text. This allows complex and repetitive documents to be written as smaller logical documents, for improved consistency, reuse, and separation of concerns.

• Extends markdown link syntax with preceding colon : (e.g. :[Title](link.md))
• Transclude local and remote (HTTP) files
• Smart indentation

Contents

• Usage
• Syntax
• API

Usage

Install Hercule using npm:

$ npm install -g hercule

Use Hercule as a command-line utility:

$ hercule src/blueprint.md -o output.md

Or, use Hercule as a library:

import { transcludeString } from 'hercule';

transcludeString('# Title\n\n:[abstract](abstract.md)', (err, output) => {
  if (err) console.log(err)
  console.log(output);
});

Syntax

Hercule extends the Markdown inline link syntax with a leading colon (:) to denote the link should be transcluded. The content of the linked file will replace the transclusion link including nested transclusion links.

The :[subject of sentence](fox.md) jumps over :[observer](dog.md).

Markdown renderers ignore the leading colon and render transclusion links as HTML links with a preceding colon.

Example 1: transclusion link

Prepend a colon (:) to a markdown link to transclude the files' content. Unauthenticated HTTP/S transclusion is also supported (e.g. :[example link](https://foo.com/bar.md).

Example 2: whitespace sensitivity

Leading whitespace is significant in Markdown. Hercule preserves whitespace when a transclusion link is preceded with only whitespace by indenting each line of the transcluded file.

Each line of currency-usd.json is indented with the whitespace preceding the transclusion link, where the transclusion link is preceded only by whitespace.

Example 3: passing context

Context can be passed through transclusion links to nested (descendent) transclusion links, and is passed by adding override arguments to the transclusion link and is scoped to the linked file and its descendants.

Each override is denoted by a target link and an overriding link (e.g. :[](foo.md BING:bar.md)). The target link and overriding link are separated by a colon. The overriding link will override all descendant links that match the target link. The overriding link may also be a double quoted string (e.g. :[](foo.md BOP:"fizz buzz").

It is clearest for overrides to use a simple string for the target link that will not be confused for a real file path.

The transclusion link :[](CODE) in payment-terms.md is targeted by the override in input.md.

Example 4: default

A link or a string can also be specified as a default when no override is supplied.

The default must immediately follow the link, is denoted by the double vertical bar (||) and may be followed by additional overrides (e.g. :[](FOO || bar.md FIZZ:buzz.md BING:"bop").

API

• TranscludeStream
• transcludeString
• transcludeFile
• Resolvers
• Custom Transclusion Syntax
• Promises

TranscludeStream(source, [options])

Returns a duplex stream.

Arguments

1. source (String): A string used for resolving relative links and generating sourcemap.
2. options (Object): An object of options to be applied when processing input.

• resolvers (Array[Function]): An array of functions which are applied to resolve the URLs to content.
• transclusionSyntax (String): Choose transclusion link syntax. Supports 'hercule', 'aglio', 'marked', 'multimarkdown'.

Customer Emitters

• sourcemap (Object): A sourcemap object will be emitted exactly once.

Examples

import { TranscludeStream } from 'hercule';

const transcluder = new TranscludeStream();

transcluder.on('error', (err) => {
  // Handle exceptions like dead links
  console.log(err);
});

// assuming input is a readable stream and output is a writable stream
input.pipe(transcluder).pipe(output);

transcludeString(str, [options], callback)

Transcludes the input str, and callback is called when finished.

Arguments

1. str (String): A string to process.
2. options (Object): An object of options to be applied when processing input.

• source (String): source file required for resolving relative links and generating sourcemap.
• resolvers (Array[Function]): An array of functions which are applied to resolve the URLs to content.
• transclusionSyntax (String): Choose transclusion link syntax. Supports 'hercule', 'aglio', 'marked', 'multimarkdown'.

3. callback(err, [output], [sourcemap]) (Function): A function that will be called after the input str has been processed.

• err (Error): An error object.
• output (String): A string containing processed input.
• sourcemap (Object): A sourcemap object.

Examples

import { transcludeString } from 'hercule';

transcludeString(':[foo](bar.md)', (err, output) => {
  // Handle exceptions like dead links
  if (err) console.log(err)
  console.log(output);
});

transcludeFile(source, [options], callback)

Transcludes the source file.

Arguments

1. source (String): A path to a file to process.
2. options (Object): An object of options to be applied when processing input.

• resolvers (Array[Function]): An array of functions which are applied to resolve the URLs to content.
• transclusionSyntax (String): Choose transclusion link syntax. Supports 'hercule', 'aglio', 'marked', 'multimarkdown'.

3. callback(err, [output], [sourcemap]) (Function): A function that will be called after the source file has been processed.

• err (Error): An error object.
• output (String): A string containing processed input.
• sourcemap (Object): A sourcemap object.

Examples

import { transcludeFile } from 'hercule';

transcludeFile('foo.md', (err, output) => {
  // Handle exceptions like dead links
  if (err) console.log(err)
  console.log(output);
});

Resolvers

Resolver functions transform urls into the input to be transcluded.

Hercule includes resolvers for http urls, local files, and strings. You can replace these with your own resolvers to customise the behaviour.

Arguments

1. url - A relative url from the input being processed.
2. source - The absolute source url of the url being resolved.

Returns

• (null): Returns null if the url cannot be resolved.
• (Object)
  • content (Stream | String): The content to be transcluded. Streams are processed for further transclusion links. Strings are assumed fully processed.
  • url (String): The absolute url of the input, allowing circular reference detection and nested transclusion.

Examples

import { transcludeFile, resolveHttpUrl, resolveLocalUrl, resolveString } from 'hercule';

function myResolver(url, source) {
  // Add your implementation here
  // Return null to try next resolver
  return null;
}

// Resolvers are tried in order
const resolvers = [myResolver, resolveHttpUrl, resolveLocalUrl, resolveString];

transcludeFile('foo.md', { resolvers }, (err, output) => {
  // Handle exceptions like dead links
  if (err) console.log(err)
  console.log(output);
});

Promises

A promise interface for transcludeString and transcludeFile is available when requiring hercule/promises.

import { transcludeString } from 'hercule/promises';

transcludeString(':[foo](bar.md)')
.then(({output}) => console.log(output))
.catch(err => console.log(err));

import { transcludeFile } from 'hercule/promises';

transcludeFile('foo.md')
.then(({output}) => console.log(output))
.catch(err => console.log(err));