including referenced files into a Markdown file
MdInclude supports four kinds of includes:
- Simple text includes with additional Markdown content
- Citation include
- CSV include with automatic conversion into a Markdown table
- Source code include with automatic derivation of syntax type from filename extension.
MdInclude supports globbing for the file path.
It can be used as a function or with Gulp.
Example files:
main.md
# Introduction
Hello, this is an include example.
<!-- #include chapters/one.md -->
<!-- #include chapters/two.md -->
chapters/one.md
# Chapter 1
This is the first chapter.
chapters/two.md
# Chapter 2
This is the second chapter.
The following call includes the referenced files:
var mdinclude = require('mdinclude');
var result = mdinclude.readFileSync('main.md');The variable result now contains the following string:
# Introduction
Hello, this is an include example.
# Chapter 1
This is the first chapter.
# Chapter 2
This is the second chapter.
Example files:
doc.md
# Quotes
<!-- #cite quotes/einstein.txt -->
Some additional content.
quotes/einstein.txt
Insanity: doing the same thing over and over again and expecting different results.
Albert Einstein
The following call includes the referenced files:
var mdinclude = require('mdinclude');
var result = mdinclude.readFileSync('doc.md');The variable result now contains the following string:
# Quotes
> Insanity: doing the same thing over and over again and expecting different results.
>
> Albert Einstein
Some additional content.
Example files:
data-table.md
# Data Document
<!-- #csv data/values.csv -->
Some additional content.
data/values.csv
"Column 1", "Column 2"
1, 2
3, 4
The following call includes the referenced files:
var mdinclude = require('mdinclude');
var result = mdinclude.readFileSync('data-table.md');The variable result now contains the following string:
# Data Document
| Column 1 | Column 2 |
|----------|----------|
| 1 | 2 |
| 3 | 4 |
Some additional content.
Example files:
doc.md
# Example Source Code
<!-- #code example.js -->
And more content.
example.js
console.log("Hello World.");The following call includes the referenced files:
var mdinclude = require('mdinclude');
var result = mdinclude.readFileSync('doc.md');The variable result now contains the following string:
# Example Source Code
```javascript
console.log("Hello World");
```
And more content.
Globbing works for all kinds of include: Markdown, citation, code, ...
Example files:
main.md
# Introduction
Hello, this is a globbing example.
<!-- #include chapters/*.md -->
chapters/01.md
# Chapter 1
This is the first chapter.
chapters/02.md
# Chapter 2
This is the second chapter.
The following call includes the referenced files:
var mdinclude = require('mdinclude');
var result = mdinclude.readFileSync('main.md');The variable result now contains the following string:
# Introduction
Hello, this is a globbing example.
# Chapter 1
This is the first chapter.
# Chapter 2
This is the second chapter.
The included file paths are sorted before including.
Therefore, the order of the included files in deterministic.
To control the order the glob path can be prefixed by sort: asc or sort: desc.
If the include statement looks like the following:
<!-- #include sort: desc chapters/*.md -->
It will result in:
# Chapter 2
This is the second chapter.
# Chapter 1
This is the first chapter.
MdInclude makes use of GulpText simple to provide the API. Therefore, it currently supports three ways of usage.
- Use the
readFileSync(path, [options])function, to get the processed content of a Markdown file. - Specify a Markdown string and an option map with the source path, to get the processed string, using the reference path to resolve relative paths in file references.
- Give no arguments or only an options map, to get a gulp transformation.
Use the function readFileSync(path) and specify a path to the Markdown file.
var mdinclude = require('mdinclude');
var result = mdinclude.readFileSync('project_a/docs/index.md');Give a file path as reference for relative paths and a string to process as Markdown text.
var mdinclude = require('mdinclude');
var documentPath = 'project_a/docs/index.md';
var documentText =
'# Introduction\n' +
'<!-- #include includes/intro.md -->\n' +
'# Dataset\n' +
'<!-- #csv values.csv -->';
var result = mdinclude(documentText, { sourcePath: documentPath });var mdinclude = require('mdinclude');
var gulp = require('gulp');
gulp.task('preprocess-markdown', function() {
return gulp.src('docs/*.md')
.pipe(mdinclude())
.pipe(gulp.dest('out'));
});MdInclude is published under the MIT license.