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
Install Hercule using npm:
$ npm install -g herculeUse Hercule as a command-line utility:
$ hercule src/blueprint.md -o output.mdOr, 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);
});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).
| Input | Output ($ hercule input.md) |
|---|---|
input.md:
This is an :[example link](foo.md). |
This is an example transclusion. |
foo.md:
example transclusion |
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.
| Input | Output ($ hercule input.md) |
|---|---|
input.md:
Currency object: |
Currency object: |
currency-usd.json:
{
"code": "USD",
"currency": "United States dollar"
}
|
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.
| Input | Output ($ hercule input.md) |
|---|---|
input.md:
# Payment Terms |
# Payment Terms |
payment-terms.md:
Payment shall be made via direct deposit in :[](CODE). |
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").
| Input | Output ($ hercule input.md) |
|---|---|
input.md:
# Payment Terms |
# Payment Terms |
payment-terms.md:
Payment shall be made via direct deposit in :[](CODE || "GBP"). |
Returns a duplex stream.
Arguments
source(String): A string used for resolving relative links and generating sourcemap.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);Transcludes the input str, and callback is called when finished.
Arguments
str(String): A string to process.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'.
callback(err, [output], [sourcemap])(Function): A function that will be called after the inputstrhas 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);
});Transcludes the source file.
Arguments
source(String): A path to a file to process.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'.
callback(err, [output], [sourcemap])(Function): A function that will be called after thesourcefile 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);
});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
url- A relative url from the input being processed.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);
});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));