{"id":29724582,"url":"https://github.com/mastersign/mdinclude","last_synced_at":"2025-07-24T21:22:16.606Z","repository":{"id":33610899,"uuid":"37263086","full_name":"mastersign/mdinclude","owner":"mastersign","description":"Includes in Markdown files.","archived":false,"fork":false,"pushed_at":"2023-07-13T10:41:43.000Z","size":304,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-07-01T11:50:51.341Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mastersign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-06-11T13:36:39.000Z","updated_at":"2022-12-14T22:32:15.000Z","dependencies_parsed_at":"2024-08-23T03:14:36.028Z","dependency_job_id":null,"html_url":"https://github.com/mastersign/mdinclude","commit_stats":{"total_commits":83,"total_committers":4,"mean_commits":20.75,"dds":0.3012048192771084,"last_synced_commit":"d84916dd7d0686dbd10f54b294efc47c52061797"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/mastersign/mdinclude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdinclude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdinclude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdinclude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdinclude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mastersign","download_url":"https://codeload.github.com/mastersign/mdinclude/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mastersign%2Fmdinclude/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266904628,"owners_count":24004135,"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","status":"online","status_checked_at":"2025-07-24T02:00:09.469Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-07-24T21:22:12.746Z","updated_at":"2025-07-24T21:22:16.587Z","avatar_url":"https://github.com/mastersign.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MdInclude\n\n[![npm package][npm-img]][npm-url]\n[![dependency status][libraries-img]][libraries-url]\n[![build status][travis-img]][travis-url]\n\n\u003e including referenced files into a [Markdown] file\n\n## Application\n\n_MdInclude_ supports four kinds of includes:\n\n* [Simple text includes](#simple-text-include) with additional [Markdown] content\n* [Citation include](#citation-include)\n* [CSV include](#csv-include) with automatic conversion into a [Markdown table][mdtables]\n* [Source code include](#source-code-include) with automatic derivation of syntax type from filename extension.\n\n_MdInclude_ supports [globbing][] for the file path.\n\nIt can be used as a function or with [Gulp].\n\n### Simple Text Include\n\nExample files:\n\n**main.md**\n\n```\n# Introduction\nHello, this is an include example.\n\u003c!-- #include chapters/one.md --\u003e\n\u003c!-- #include chapters/two.md --\u003e\n```\n\n**chapters/one.md**\n\n```\n# Chapter 1\nThis is the first chapter.\n```\n\n**chapters/two.md**\n\n```\n# Chapter 2\nThis is the second chapter.\n```\n\nThe following call includes the referenced files:\n\n```js\nvar mdinclude = require('mdinclude');\nvar result = mdinclude.readFileSync('main.md');\n```\n\nThe variable `result` now contains the following string:\n\n```\n# Introduction\nHello, this is an include example.\n# Chapter 1\nThis is the first chapter.\n# Chapter 2\nThis is the second chapter.\n```\n\n### Citation Include\n\nExample files:\n\n**doc.md**\n\n```\n# Quotes\n\n\u003c!-- #cite quotes/einstein.txt --\u003e\n\nSome additional content.\n```\n\n**quotes/einstein.txt**\n\n```\nInsanity: doing the same thing over and over again and expecting different results.\n\nAlbert Einstein\n```\n\nThe following call includes the referenced files:\n\n```js\nvar mdinclude = require('mdinclude');\nvar result = mdinclude.readFileSync('doc.md');\n```\n\nThe variable `result` now contains the following string:\n\n```\n# Quotes\n\n\u003e Insanity: doing the same thing over and over again and expecting different results.\n\u003e\n\u003e Albert Einstein\n\nSome additional content.\n```\n\n### CSV Include\n\nExample files:\n\n**data-table.md**\n\n```\n# Data Document\n\n\u003c!-- #csv data/values.csv --\u003e\n\nSome additional content.\n```\n\n**data/values.csv**\n\n```csv\n\"Column 1\", \"Column 2\"\n1, 2\n3, 4\n```\n\nThe following call includes the referenced files:\n\n```js\nvar mdinclude = require('mdinclude');\nvar result = mdinclude.readFileSync('data-table.md');\n```\n\nThe variable `result` now contains the following string:\n\n```\n# Data Document\n\n| Column 1 | Column 2 |\n|----------|----------|\n| 1 | 2 |\n| 3 | 4 |\n\nSome additional content.\n```\n\n### Source Code Include\n\nExample files:\n\n**doc.md**\n\n```\n# Example Source Code\n\n\u003c!-- #code example.js --\u003e\n\nAnd more content.\n```\n\n**example.js**\n\n```js\nconsole.log(\"Hello World.\");\n```\n\nThe following call includes the referenced files:\n\n```js\nvar mdinclude = require('mdinclude');\nvar result = mdinclude.readFileSync('doc.md');\n```\n\nThe variable `result` now contains the following string:\n\n    # Example Source Code\n\n    ```javascript\n    console.log(\"Hello World\");\n    ```\n\n    And more content.\n\n## Globbing\n\nGlobbing works for all kinds of include: Markdown, citation, code, ...\n\nExample files:\n\n**main.md**\n\n```\n# Introduction\nHello, this is a globbing example.\n\u003c!-- #include chapters/*.md --\u003e\n```\n\n**chapters/01.md**\n\n```\n# Chapter 1\nThis is the first chapter.\n```\n\n**chapters/02.md**\n\n```\n# Chapter 2\nThis is the second chapter.\n```\n\nThe following call includes the referenced files:\n\n```js\nvar mdinclude = require('mdinclude');\nvar result = mdinclude.readFileSync('main.md');\n```\n\nThe variable `result` now contains the following string:\n\n```\n# Introduction\nHello, this is a globbing example.\n# Chapter 1\nThis is the first chapter.\n# Chapter 2\nThis is the second chapter.\n```\n\nThe included file paths are sorted before including.\nTherefore, the order of the included files in deterministic.\nTo control the order the glob path can be prefixed by `sort: asc` or `sort: desc`.\n\nIf the include statement looks like the following:\n\n```\n\u003c!-- #include sort: desc chapters/*.md --\u003e\n```\n\nIt will result in:\n\n```\n# Chapter 2\nThis is the second chapter.\n# Chapter 1\nThis is the first chapter.\n```\n\n## Interface\n\n_MdInclude_ makes use of [GulpText _simple_][gulp-text-simple] to provide the API.\nTherefore, it currently supports three ways of usage.\n\n1. Use the `readFileSync(path, [options])` function, to get the processed\n   content of a Markdown file.\n2. Specify a Markdown string and an option map with the source path,\n   to get the processed string, using the reference path to resolve\n   relative paths in file references.\n3. Give no arguments or only an options map, to get a gulp transformation.\n\n### Transform a file directly\n\nUse the function `readFileSync(path)` and specify a path to the Markdown file.\n\n```js\nvar mdinclude = require('mdinclude');\nvar result = mdinclude.readFileSync('project_a/docs/index.md');\n```\n\n### Transform a string with a source path\n\nGive a file path as reference for relative paths and a string\nto process as Markdown text.\n\n```js\nvar mdinclude = require('mdinclude');\nvar documentPath = 'project_a/docs/index.md';\nvar documentText =\n\t'# Introduction\\n' +\n\t'\u003c!-- #include includes/intro.md --\u003e\\n' +\n\t'# Dataset\\n' +\n\t'\u003c!-- #csv values.csv --\u003e';\nvar result = mdinclude(documentText, { sourcePath: documentPath });\n```\n\n### Create a Gulp transformation\n\n```js\nvar mdinclude = require('mdinclude');\nvar gulp = require('gulp');\n\ngulp.task('preprocess-markdown', function() {\n\treturn gulp.src('docs/*.md')\n\t\t.pipe(mdinclude())\n\t\t.pipe(gulp.dest('out'));\n});\n```\n\n## License\n\n_MdInclude_ is published under the MIT license.\n\n[npm-url]: https://www.npmjs.com/package/mdinclude\n[npm-img]: https://img.shields.io/npm/v/mdinclude.svg\n[libraries-url]: https://libraries.io/npm/mdinclude\n[libraries-img]: https://img.shields.io/librariesio/github/mastersign/mdinclude.svg\n[travis-img]: https://img.shields.io/travis/mastersign/mdinclude/master.svg\n[travis-url]: https://travis-ci.org/mastersign/mdinclude\n[Gulp]: http://gulpjs.com\n[Markdown]: https://daringfireball.net/projects/markdown/\n[mdtables]: https://michelf.ca/projects/php-markdown/extra/#table\n[gulp-text-simple]: https://www.npmjs.com/package/gulp-text-simple\n[globbing]: https://github.com/isaacs/node-glob#glob-primer","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastersign%2Fmdinclude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmastersign%2Fmdinclude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmastersign%2Fmdinclude/lists"}