Markdown-includes NPM

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.

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 from glob 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 is 3.
--no-comments: Remove comments from the output file. System default is false.
--root <path>: Specify the root folder. System default is the current working directory.
--config <path> | -c: Specify the config file. System default is mdi.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 the chapters 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 is 3.

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 the path from the config if not specified.
watch(path?: string, debug?: boolean): Watch the file for changes and recompile when it changes. Uses node-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 or fix/fix-name.