开源软件名称（OpenSource Name）：

开源软件地址(OpenSource Url)：

开源编程语言(OpenSource Language)：

开源软件介绍(OpenSource Introduction)：

Table of Contents

• markdown-include
  • Compile your markdown files
  • Make a table of contents
• How To Install
• How To Use From The Command Line
  • markdown.json
• How To Use As A Module
  • API
    • buildLink
    • buildLinkString
    • compileFiles
    • compileHeadingTags
    • findHeadingTags
    • findIncludeTags
    • parseHeadingTag
    • parseIncludeTag
    • processFile
    • processIncludeTags
    • replaceIncludeTags
    • replaceWith
    • resolveCustomTags
    • stripTag
    • stripTagsInFile
    • writeFile
• How To Make Plugins
  • Tutorial
• How It Works
• License

markdown-include

markdown-include is built using Node.js and allows you to include markdown files into other markdown files using a C style include syntax.

Compile your markdown files

markdown-include's main feature is that it allows you to include markdown files into other markdown files. For example, you could place the following into a markdown file:

#include "markdown-file.md"
#include "another-markdown-file.md"

And assuming that markdown.file.md contents are:

Something in markdown file!

And assuming that another-markdown-file.md contents are:

Something in another markdown file!

It would compile to:

Something in markdown file!
Something in another markdown file!

Pretty neat, huh?

Make a table of contents

Aside from compiling your markdown files, markdown-include can also build your table of contents. This works by evaluating the heading tags inside of your files. Since markdown works on using # for making HTML headings, this makes it easy to assemble table of contents from them. The more # you have in front of your headings (up to 6) will decide how the table of contents is built. Use one # and it's a top level navigation item... Use two # and it would be underneath the previous navigation item and so on.

For each heading that you would like to be included in a table of contents just add !heading to the end of it.

How To Install

markdown-include is available on npm for easy installation:

npm install markdown-include

Use the -g flag if you wish to install markdown-include globally on your system. Use the --save flag to save in your package.json file in your local project.

How To Use From The Command Line

markdown-include is very easy to use whether on the command line or in your own node project. Each can help you compile your markdown files as you see fit. markdown-include does require that you define a markdown.json file with your options for compile. See below for all of the options available to you.

Run from the command line to compile your documents like so:

node_modules/bin/cli.js path/to/markdown.json

markdown.json

markdown.json can be populated with the following options:

How To Use As A Module

Just require in your node project:

var markdownInclude = require('markdown-include');

From there, you can use markdown-include's API to fit your needs.

API

When using as a module, markdown-include offers an API for you to work with markdown files as detailed below:

buildLink

Description

A method for making markdown style anchor tags.

Signature

buildLink(title: String, anchor: String) => String

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.buildLink("My Link String", "#my-link-string"); // [My Link String](#my-link-string)

buildLinkString

Description

A method for taking strings and building friendly markdown links. This is mostly used internally for building the table of contents.

Signature

buildLinkString(str: String) => String

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.buildLinkString("My Link String"); // my-link-string

compileFiles

Description

This is probably the most important method in markdown-include. It takes a path to your markdown.json file, reads your options and returns a promise. When the promise is resolved it returns the data to you. This is exactly the same as running markdown-include in the command line as it runs through the whole lifecycle.

Signature

compileFiles(path: String) => Object<Promise>

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.compileFiles("path/to/markdown.json").then(function (data) {
	// do something with compiled files
});

compileHeadingTags

Description

A method for compiling heading tags (!heading) in a given file.

Signature

compileHeadingTags(file: String)

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.compileHeadingTags("my_file.md");

findHeadingTags

Description

A method for finding heading tags (!heading) in a string.

Signature

findHeadingTags(data: String) => Array<String>

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.findHeadingTags("### A Heading !heading"); // [ "### A Heading !heading" ]

findIncludeTags

Description

A method for finding include tags (#include "my-include.md") in a string.

Signature

findIncludeTags(data: String) => Array<String>

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.findIncludeTags('#include "my-include.md"'); // [ '#include "my-include.md"' ]

parseHeadingTag

Description

Parses a heading tag based on the amount of asterisks present before it (### Heading)

Signature

parseHeadingTag(headingTag: String) => Object<count: Number, headingTag: String>

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.parseHeadingTag('### Heading'); // { count: 3, headingTag: 'Heading' }

parseIncludeTag

Description

Parses a include tag (#include "my-include.md")

Signature

parseIncludeTag(tag: String) => String

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.parseIncludeTag('#include "my-include.md"'); // "my-include.md"

processFile

Description

Processes a file and adds it to the build object for compiling.

Signature

processFile(file: String, currentFile: String)

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.processFile('another-include.md', 'my-include.md');

processIncludeTags

Description

Processes a file and adds it to the build object for compiling.

Signature

processIncludeTags(file: String, currentFile: String, tags: Array<String>) => Array<String>

Parameters

Example

var markdownInclude = require('markdown-include');
markdownInclude.processIncludeTags('another-include.md', 'my-include.md', ['one-include.md']); // ['one-include.md']

replaceIncludeTags

Description

Replaces include tags in given file with actual data (file must be added to build object first with processFile).

Signature

replaceIncludeTags(file: String) => String

Parameters

Example

var markdownInclude = require