{"id":19499955,"url":"https://github.com/sethen/markdown-include","last_synced_at":"2025-04-05T15:07:51.150Z","repository":{"id":27466416,"uuid":"30945571","full_name":"sethen/markdown-include","owner":"sethen","description":":page_with_curl: Include markdown files into other markdown files with C style syntax","archived":false,"fork":false,"pushed_at":"2022-04-20T18:01:40.000Z","size":66,"stargazers_count":150,"open_issues_count":14,"forks_count":74,"subscribers_count":6,"default_branch":"develop","last_synced_at":"2025-03-29T14:08:40.814Z","etag":null,"topics":["c-style","javascript","markdown","markdown-include"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sethen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-02-18T00:34:32.000Z","updated_at":"2025-02-05T05:13:29.000Z","dependencies_parsed_at":"2022-08-12T00:50:10.494Z","dependency_job_id":null,"html_url":"https://github.com/sethen/markdown-include","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethen%2Fmarkdown-include","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethen%2Fmarkdown-include/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethen%2Fmarkdown-include/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethen%2Fmarkdown-include/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethen","download_url":"https://codeload.github.com/sethen/markdown-include/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247353746,"owners_count":20925329,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c-style","javascript","markdown","markdown-include"],"created_at":"2024-11-10T22:07:02.965Z","updated_at":"2025-04-05T15:07:51.121Z","avatar_url":"https://github.com/sethen.png","language":"JavaScript","readme":"# Table of Contents\n\n* [markdown-include](#markdown-include)\n  * [Compile your markdown files](#compile-your-markdown-files)\n  * [Make a table of contents](#make-a-table-of-contents)\n* [How To Install](#how-to-install)\n* [How To Use From The Command Line](#how-to-use-from-the-command-line)\n  * [markdown.json](#markdown-json)\n* [How To Use As A Module](#how-to-use-as-a-module)\n  * [API](#api)\n    * [`buildLink`](#buildlink)\n    * [`buildLinkString`](#buildlinkstring)\n    * [`compileFiles`](#compilefiles)\n    * [`compileHeadingTags`](#compileheadingtags)\n    * [`findHeadingTags`](#findheadingtags)\n    * [`findIncludeTags`](#findincludetags)\n    * [`parseHeadingTag`](#parseheadingtag)\n    * [`parseIncludeTag`](#parseincludetag)\n    * [`processFile`](#processfile)\n    * [`processIncludeTags`](#processincludetags)\n    * [`replaceIncludeTags`](#replaceincludetags)\n    * [`replaceWith`](#replacewith)\n    * [`resolveCustomTags`](#resolvecustomtags)\n    * [`stripTag`](#striptag)\n    * [`stripTagsInFile`](#striptagsinfile)\n    * [`writeFile`](#writefile)\n* [How To Make Plugins](#how-to-make-plugins)\n  * [Tutorial](#tutorial)\n* [How It Works](#how-it-works)\n* [License](#license)\n\n\n# markdown-include\n\n[![Build Status](https://travis-ci.org/sethen/markdown-include.svg?branch=master)](https://travis-ci.org/sethen/markdown-include)\n\nmarkdown-include is built using Node.js and allows you to include markdown files into other markdown files using a C style include syntax.\n\n## Compile your markdown files\n\nmarkdown-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:\n\n```\n#include \"markdown-file.md\"\n#include \"another-markdown-file.md\"\n```\n\nAnd assuming that `markdown.file.md` contents are:\n\n```\nSomething in markdown file!\n```\n\nAnd assuming that `another-markdown-file.md` contents are: \n\n```\nSomething in another markdown file!\n``` \n\nIt would compile to:\n\n```\nSomething in markdown file!\nSomething in another markdown file!\n```\n\nPretty neat, huh?\n\n## Make a table of contents\n\nAside 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.\n\nFor each heading that you would like to be included in a table of contents just add ` !heading` to the end of it.\n\n\n# How To Install\n\nmarkdown-include is available on npm for easy installation:\n\n```\nnpm install markdown-include\n```\n\nUse 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.\n\n\n# How To Use From The Command Line\n\nmarkdown-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.\n\nRun from the command line to compile your documents like so:\n\n```\nnode_modules/bin/cli.js path/to/markdown.json\n```\n\n\n## markdown.json\n\n`markdown.json` can be populated with the following options:\n\n| Option                    | Type    | Description                                                                |\n|:-------------------------:|:-------:|:--------------------------------------------------------------------------:|\n| `build`                   | String  | File path of where everything should be compiled, like `README.md`.        |\n| `files`                   | Array   | Array of files to to compile.                                              |\n| `tableOfContents`         | Object  | Object to hold options for table of contents generation.                   |\n| `tableOfContents.heading` | String  | Heading for table of contents (use markdown syntax if desired).            |\n| `tableOfContents.lead`    | String  | What navigation items in table of contents lead with.  If value is `number` will add numbers before each item and subitem.  If not, will add asterisks.  Refer to markdown syntax to understand the difference. |\n# How To Use As A Module\n\nJust require in your node project:\n\n```\nvar markdownInclude = require('markdown-include');\n```\n\nFrom there, you can use markdown-include's API to fit your needs.\n\n\n## API\n\nWhen using as a module, markdown-include offers an API for you to work with markdown files as detailed below:\n\n---\n\n### `buildLink`\n\n#### Description\n\nA method for making markdown style anchor tags.\n\n#### Signature\n\n`buildLink(title: String, anchor: String) =\u003e String`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                          |\n|:---------------:|:--------:|:------------------------------------:|\n| `title`         | `String` | Title of markdown style link.        |\n| `anchor`        | `String` | Markdown style anchor for linking.   |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.buildLink(\"My Link String\", \"#my-link-string\"); // [My Link String](#my-link-string)\n```\n\n---\n### `buildLinkString`\n\n#### Description\n\nA method for taking strings and building friendly markdown links.  This is mostly used internally for building the table of contents.\n\n#### Signature\n\n`buildLinkString(str: String) =\u003e String`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                                                            |\n|:---------------:|:--------:|:----------------------------------------------------------------------:|\n| `str`           | `String` | File path of where everything should be compiled, like `README.md`.    |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.buildLinkString(\"My Link String\"); // my-link-string\n```\n\n---\n### `compileFiles`\n\n#### Description\n\nThis 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.\n\n#### Signature\n\n`compileFiles(path: String) =\u003e Object\u003cPromise\u003e` \n\n#### Parameters\n\n| Parameter(s)   | Type     | Description                                              |\n|:--------------:|:--------:|:--------------------------------------------------------:|\n| `path`         | `String` | Compiles files when given the path to `markdown.json`    |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.compileFiles(\"path/to/markdown.json\").then(function (data) {\n\t// do something with compiled files\n});\n```\n\n---\n### `compileHeadingTags`\n\n#### Description\n\nA method for compiling heading tags (`!heading`) in a given file.\n\n#### Signature\n\n`compileHeadingTags(file: String)`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                          |\n|:---------------:|:--------:|:------------------------------------:|\n| `file`          | `String` | File with `!heading` tags            |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.compileHeadingTags(\"my_file.md\");\n```\n\n---\n### `findHeadingTags`\n\n#### Description\n\nA method for finding heading tags (`!heading`) in a string.\n\n#### Signature\n\n`findHeadingTags(data: String) =\u003e Array\u003cString\u003e`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                          |\n|:---------------:|:--------:|:------------------------------------:|\n| `data`          | `String` | Data with `!heading` tags            |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.findHeadingTags(\"### A Heading !heading\"); // [ \"### A Heading !heading\" ]\n```\n\n---\n### `findIncludeTags`\n\n#### Description\n\nA method for finding include tags (`#include \"my-include.md\"`) in a string.\n\n#### Signature\n\n`findIncludeTags(data: String) =\u003e Array\u003cString\u003e`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                                  |\n|:---------------:|:--------:|:--------------------------------------------:|\n| `data`          | `String` | Data with `#include \"my-include.md\"` tags    |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.findIncludeTags('#include \"my-include.md\"'); // [ '#include \"my-include.md\"' ]\n```\n\n---\n### `parseHeadingTag`\n\n#### Description\n\nParses a heading tag based on the amount of asterisks present before it (`### Heading`)\n\n#### Signature\n\n`parseHeadingTag(headingTag: String) =\u003e Object\u003ccount: Number, headingTag: String\u003e`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                                  |\n|:---------------:|:--------:|:--------------------------------------------:|\n| `headingTag`    | `String` | Heading tag to parse                         |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.parseHeadingTag('### Heading'); // { count: 3, headingTag: 'Heading' }\n```\n\n---\n### `parseIncludeTag`\n\n#### Description\n\nParses a include tag (`#include \"my-include.md\"`)\n\n#### Signature\n\n`parseIncludeTag(tag: String) =\u003e String`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                                  |\n|:---------------:|:--------:|:--------------------------------------------:|\n| `tag`           | `String` | Heading tag to parse                         |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.parseIncludeTag('#include \"my-include.md\"'); // \"my-include.md\"\n```\n\n---\n### `processFile`\n\n#### Description\n\nProcesses a file and adds it to the build object for compiling.\n\n#### Signature\n\n`processFile(file: String, currentFile: String)`\n\n#### Parameters\n\n| Parameter(s)    | Type     | Description                                                           |\n|:---------------:|:--------:|:---------------------------------------------------------------------:|\n| `file`          | `String` | File for processing                                                   |\n| `currentFile`   | `String` | Current file include file was found in for additional processing      |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.processFile('another-include.md', 'my-include.md');\n```\n\n---\n### `processIncludeTags`\n\n#### Description\n\nProcesses a file and adds it to the build object for compiling.\n\n#### Signature\n\n`processIncludeTags(file: String, currentFile: String, tags: Array\u003cString\u003e) =\u003e Array\u003cString\u003e`\n\n#### Parameters\n\n| Parameter(s)    | Type            | Description                                                           |\n|:---------------:|:---------------:|:---------------------------------------------------------------------:|\n| `file`          | `String`        | File for processing                                                   |\n| `currentFile`   | `String`        | Current file include file was found in for additional processing      |\n| `tags`          | `Array\u003cString\u003e` | Current file include file was found in for additional processing      |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.processIncludeTags('another-include.md', 'my-include.md', ['one-include.md']); // ['one-include.md']\n```\n\n---\n### `replaceIncludeTags`\n\n#### Description\n\nReplaces include tags in given file with actual data (file must be added to build object first with `processFile`).\n\n#### Signature\n\n`replaceIncludeTags(file: String) =\u003e String`\n\n#### Parameters\n\n| Parameter(s)    | Type            | Description                        |\n|:---------------:|:---------------:|:----------------------------------:|\n| `file`          | `String`        | File to replace include tags       |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.replaceIncludeTags('my-include.md'); // 'Content in my-include.md!'\n```\n\n---\n### `replaceWith`\n\n#### Description\n\nUtility method for transforming a string.\n\n#### Signature\n\n`replaceWith(Object\u003cstring: String, index: Number, preserve: Boolean, replacement: String\u003e) =\u003e String`\n\n#### Parameters\n\n| Parameter(s)      | Type            | Description                            |\n|:-----------------:|:---------------:|:--------------------------------------:|\n| `obj.string`      | `String`        | String to transform                    |\n| `obj.index`       | `Number`        | Index to start transformation to end   |\n| `obj.preserve`    | `Boolean`       | Preserve original string               |\n| `obj.replacement` | `String`        | String to use for replacement          |\n\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.replaceWith({\n\tstring: \"string\",\n\tindex: 4,\n\treplacement: \"myString\"\n}); // 'somemyString'\n```\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.replaceWith({\n\tstring: \"string\",\n\tindex: 4,\n\tpreserve: true,\n\treplacement: \"myString\"\n}); // 'somemyStringthing'\n```\n\n---\n### `resolveCustomTags`\n\n#### Description\n\nMethod for resolving custom tags.  Looks in `customTags` object attached to markdown include module.\n\n#### Signature\n\n`resolveCustomTags(data: String) =\u003e String` \n\n#### Parameters\n\n| Parameter(s)      | Type            | Description                            |\n|:-----------------:|:---------------:|:--------------------------------------:|\n| `data`            | `String`        | String with custom tags                |\n\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.resolveCustomTags('### Custom Tag !myCustomTag');\n```\n\n---\n### `stripTag`\n\n#### Description\n\nMethod for stripping tags in a string.\n\n#### Signature\n\n`stripTag(Object\u003ctag: String, pattern: String\u003e) =\u003e String` \n\n#### Parameters\n\n| Parameter(s)      | Type            | Description                            |\n|:-----------------:|:---------------:|:--------------------------------------:|\n| `obj.tag`         | `String`        | String with tag in it                  |\n| `obj.pattern`     | `String`        | Pattern to replace in tag              |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.stripTag('### Custom Tag !myCustomTag'); // ### Custom Tag\n```\n\n---\n### `stripTagsInFile`\n\n#### Description\n\nStrips tags in a given file.\n\n#### Signature\n\n`stripTag(Object\u003cdata: String, pattern: String, string: String, replace: String|Function\u003e) =\u003e String` \n\n#### Parameters\n\n| Parameter(s)      | Type                | Description                            |\n|:-----------------:|:-------------------:|:--------------------------------------:|\n| `obj.data`        | `String`            | Data with tags to strip                |\n| `obj.pattern`     | `String`            | Pattern to look for                    |\n| `obj.string`      | `String`            | String to replace                      |\n| `obj.replace`     | `String|Function`   | String or function to replace with     |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.stripTagsInFile({\n\tdata: 'String with tags !ignore',\n\tpattern: \u003cRegExp\u003e,\n\tstring: '!ignore'\n});\n```\n\n---\n### `writeFile`\n\n#### Description\n\nWriting contents to a file using the file path outlined in `markdown.json`.\n\n#### Signature\n\n`stripTag(parsedData: String) =\u003e Object\u003cPromise\u003e` \n\n#### Parameters\n\n| Parameter(s)      | Type            | Description                            |\n|:-----------------:|:---------------:|:--------------------------------------:|\n| `parsedData`      | `String`        | String to write                        |\n\n#### Example\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.writeFile('contents').then(function (data) {\n\t// continue...\n});\n```\n\n---\n# How To Make Plugins\n\nPlugins are now supported as of 0.4.0 of markdown-include.  Adding plugins to markdown-include to facilitate the transformation of custom tags is quite trivial.\n\nPlugins are best used when markdown-include is being required as a module.  If you wish to make this available via the command line, you must require markdown-include in a node module and call it from the command line.\n\n## Tutorial\n\nLet's pretend we want to add a custom tag called `!myTag` that follows the pattern of `#phrase !myTag`.  All we need to do is register the plugin with markdown-include\n\nFirst, require markdown-include:\n\n```javascript\nvar markdownInclude = require('markdown-include');\n```\n\nSecond, register your plugin with with your desired pattern to match and desired replacement.  You can replace your tag with another string to do your desired work:\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.registerPlugin({\n\tpattern: /^#.+ !myTag/gm,\n\treplace: 'myString!'\n});\n```\n\nIn the example above, we're just replacing our tag with a string.  If you would rather use a function, you can do this like so (you must return a value to replace with):\n\n```javascript\nvar markdownInclude = require('markdown-include');\nmarkdownInclude.registerPlugin({\n\tpattern: /^#.+ !myTag/gm,\n\treplace: function (tag) {\n\t\t// do something with tag...\n\t\treturn 'myString!'\n\t}\n});\n```\n\n`pattern` is the regular expression that should be looked for.  `replace` is your desired replacement for the tag once it's found.\n\nThis gives you free range to do whatever you want with the tag you want to replace.  Once the tag is encountered markdown-include will run the function.\n\nAfter the tag and it's replacement is registered, it's business as usual:\n\n```javascript\nmarkdownInclude.compileFiles('../path/to/markdown.json').then(function () {\n\t// do something after compiling\n});\n```\n\nYou can also use another form of registering a plugins if it fits your coding style better:\n\n```javascript\nmarkdownInclude.registerPlugin(/^#.+ !myTag/gm, function (tag) {\n\treturn 'my replacement!';\n});\n```\n\n\n# How It Works\n\nmarkdown-include works by recursively going through files based on the tags that are found.  For instance, consider the following in a `_README.md` file:\n\n```\n#include \"first-file.md\"\n```\n\nLet's also consider that `first-file.md` contains the following:\n\n```\n#include \"third-file.md\"\n```\n\nLet's also consider that `markdown.json` contains the following:\n\n```json\n{\n\t\"build\" : \"README.md\",\n\t\"files\" : [\"_README.md\"]\n}\n```\n\nmarkdown-include will first read the contents of `_README.md` and look for include tags.  It will find `#include \"first-file.md\"` first.  From there it will parse the tag, open `first-fild.md` and find include tags in that file.  This process continues until no more include tags are found.  \n\nAt that point it will start over in the original file and parse other include tags if they exist.  Along the way, markdown-include will parse each file and keep a record of the contents.  Once the process is finished, a file will be written in `README.md` with all of the compiled content.\n\nAs you can see, you only need to reference one file which would be `_README.md`.  We didn't need to add `first-file.md` or `third-file.md`... markdown-include does that compiling for us by making an internal chain.\n\n**NOTE**:  You must provide markdown-include with the entire file path you're trying to find in your working directory.  For example, if `first-file.md` and `third-file.md` were in the `docs` directory together and `first-file.md` was trying to include `third-file.md` you would need to do the following in `first-file.md`:\n\n```\n#include \"docs/third-file.md\"\n```\n\nThis is because markdown-include doesn't make any assumptions about where your files are.  Use the correct paths or you could run into errors!\n# License\n\nISC License\n\nCopyright (c) 2015-2016, Sethen Maleno\n\nPermission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethen%2Fmarkdown-include","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethen%2Fmarkdown-include","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethen%2Fmarkdown-include/lists"}