markdown-includes
Compile multiple Markdown files into 1, easily create a menu, remove comments and more with easy to use tags.
Features
✅ Easy to use within your new or existing projects.⌚ Compile multiple Markdown files into 1 with the&|include
tag.🗃️ Create a menu of contents with the&|menu
tag.🧹 Remove comments from output file with the&|no_comments
tag.📝 Create a table based on JSON with the&|table
tag.
Table of contents
Usage
-
Create a markdown file with any name, e.g.
index.md
. -
Install the compiler globally or locally in your project:
# npm npm install -g markdown-includes # or yarn yarn global add markdown-includes # or pnpm pnpm install -g markdown-includes
Or install it locally in your project:
# npm npm install markdown-includes
-
Choose your method to run the compiler: CLI (as shown in this chapter) or API.
mdi <input file> [options]
Or if you installed it locally:
npx mdi <input file> [options]
Multiple files When you want to compile multiple files, use the
*
as the<input file>
, like this:mdi ./*
.
It will compile all files in the current directory specified:mdi examples/*
will compile all inside examples.⚠️ The patterns are fromglob
on npm.
Hierarchy of options
The options are set with the following order of priority:
CLI arguments > Config file > Tag options > System default
Options
-
--debug
: See what is logged to the console. -
--out <file>
: Specify the output file. If not specified, the output will be written to the console. -
--version
|-v
: Show the version number. -
--help
|-h
: Show the help. -
--watch
|-w
: Watch the input file for changes and recompile when it changes. -
--menu-depth <number>
: Specify the default system depth of the menu. System default is3
. -
--no-comments
: Remove comments from the output file. System default isfalse
. -
--root <path>
: Specify the root folder. System default is the current working directory. -
--config <path>
|-c
: Specify the config file. System default ismdi.config.js
in the current working directory. -
--extensions <list>
Set the extensions to include. (default:.md,.mdx
) -
--ignore <list>
: Set the folders to ignore. (default:node_modules,.git
)
Tag Examples
Include file
Options
-
&|include include.md
: Include a file. -
&|include `chapters/**/*`
: Include all files in thechapters
folder and all subfolders, due to markdown syntax, you need to use backticks to wrap the pattern.
Input
# Title
&|include include.md
Output
# Title
This is the included file.
Include menu
Easily create a menu of contents with the &|menu
tag. The menu will be created based on the headings in the document, at the location of the tag.
Input
# Document
&|menu
## 1. Test
### Sub item
Options
-
&|menu 3
: Specify the depth of the menu in a specific document. Document default is3
.
Output
# Document
- [Document](#document)
- [1. Test](#1-test)
- [Sub item](#sub-item)
## Test
### Sub item
No comments in output file
No more removing comments, just use this tag and all comments (inline, single or multi-line) will be stripped from the output.
Input
&|no_comments
## Markdown test
Lorum ipsum
<!-- this is a comment -->
Output
## Markdown test
Lorum ipsum
Table
Use the &|table
tag to include a table from a JSON file.
For example, if you have a JSON file with the following data:
[
{
"Name": "John",
"Age": 20
},
{
"Name": "Jane",
"Age": 21
}
]
Options
-
&|table <path> <keys?>
: Specify the keys to include in the table. If no keys are specified, all keys will be included.⚠️ The keys are case sensitive.
Input
&|table data.json
Output
| Name | Age |
| ---- | --- |
| John | 20 |
| Jane | 21 |
| ... | ... |
API Usage
Configuration
When you want to use the API, you can use the default exported class to create a new compiler instance.
const create = require("markdown-includes");
const config = {
debug: true, // log actions to the console
output: "./out", // output directory
menuDepth: 3, // default menu depth
noComments: false, // remove comments from output
root: "./", // root directory
path: "path-to-file.md", // path to file
extensions: [".md", ".mdx"], // file-extensions to include
ignore: ["node_modules", ".git"], // folders to ignore
};
const compiler = await create(config);
// will use the path from the config, or path specified as an argument.
compiler.compile();
Or TypeScript:
import create, { Config } from "markdown-includes";
const config: Config = {
...
};
const compiler = await create(config);
compiler.compile();
The compiler can also read the config from a file. The config file should export the config object.
import create from "markdown-includes";
const compiler = await create({ config: "./path-to-config.js" });
compiler.compile();
Methods
-
compile(path?: string) => Promise<void>
: Compile the file.-
path
: The path to the file. Uses thepath
from the config if not specified.
-
-
watch(path?: string, debug?: boolean)
: Watch the file for changes and recompile when it changes. Usesnode-watch
on npm.-
path
: The path to the file. -
debug
: Whether to log the actions to the console.
-
-
table(content: string, columns?: string[], debug?: boolean) => Promise<string[]>
)-
content
: The content of the file. -
columns
: The columns to include in the table. -
debug
: Whether to log the actions to the console.
-
-
parse(content: string, dir: string, menuDepth: number, noComments: boolean, debug?: boolean) => Promise<string>
: Parse the content of the file.-
content
: The content of the file. -
dir
: The directory of the file. Used to resolve recursive includes. -
menuDepth
: The depth of the menu. -
noComments
: Whether to remove comments from the output. -
debug
: Whether to log the actions to the console.
-
Contributing
Contributions are welcome! Please open an issue or a pull request if you want to contribute.
Guidelines:
- Use
npm
to install dependencies. - Use
npm run build
to build the project.
- Use
npm run lint
to lint the project. - Files should be formatted with
prettier
according to the.prettierrc.json
file. - Files should be linted with
eslint
according to the.eslintrc.json
file. - Pull requests should be made to the
dev
branch. - Pull requests should be made with a description of the changes.
- Pull requests have according branches, for example:
feature/feature-name
orfix/fix-name
.
When ready to push a feature or fix, please make sure to run npm run build
and npm run lint
before pushing.
Guidelines are not set in stone, so if you have a better idea, please open an issue or a pull request.
License
MIT