markdown-includes
TypeScript icon, indicating that this package has built-in type declarations

0.9.8 • Public • Published

markdown-includes

Bundle size  Downloads  License  Version  GitHub Repo stars  GitHub issues

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

  1. Create a markdown file with any name, e.g. index.md.

  2. 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
  3. 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.

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

Authors

m10rten

Package Sidebar

Install

npm i markdown-includes

Weekly Downloads

42

Version

0.9.8

License

MIT

Unpacked Size

47.4 kB

Total Files

23

Last publish

Collaborators

  • m10rten