{"id":15776055,"url":"https://github.com/mkdoc/mkdoc","last_synced_at":"2025-05-07T08:13:50.742Z","repository":{"id":57298874,"uuid":"53757541","full_name":"mkdoc/mkdoc","owner":"mkdoc","description":"Markdown processing tools","archived":true,"fork":false,"pushed_at":"2019-10-30T21:45:16.000Z","size":512,"stargazers_count":32,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-07T08:13:40.950Z","etag":null,"topics":["ast","commonmark","html","man","markdown","stream","xml","yaml"],"latest_commit_sha":null,"homepage":null,"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/mkdoc.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":"2016-03-12T23:01:51.000Z","updated_at":"2024-12-11T22:13:08.000Z","dependencies_parsed_at":"2022-08-26T18:12:38.914Z","dependency_job_id":null,"html_url":"https://github.com/mkdoc/mkdoc","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkdoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkdoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkdoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkdoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkdoc","download_url":"https://codeload.github.com/mkdoc/mkdoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252839296,"owners_count":21812090,"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":["ast","commonmark","html","man","markdown","stream","xml","yaml"],"created_at":"2024-10-04T17:04:39.034Z","updated_at":"2025-05-07T08:13:50.713Z","avatar_url":"https://github.com/mkdoc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Markdown Tools\n\n[![Build Status](https://travis-ci.org/mkdoc/mkdoc.svg?v=2)](https://travis-ci.org/mkdoc/mkdoc)\n[![npm version](http://img.shields.io/npm/v/mkdoc.svg?v=2)](https://npmjs.org/package/mkdoc)\n[![Coverage Status](https://coveralls.io/repos/mkdoc/mkdoc/badge.svg?branch=master\u0026service=github\u0026v=2)](https://coveralls.io/github/mkdoc/mkdoc?branch=master)\n\n\u003e Make markdown documents\n\nCreates stream pipelines that convert input [commonmark][] to an abstract syntax tree and transforms the tree; the result is then typically converted back to markdown or to another format such as HTML, XML or JSON.\n\n## Install\n\n```\nnpm i -g mkdoc\n```\n\n## Features\n\n* Command line and programmatic control.\n* Streaming build system, see [mktask][].\n* DSL for including files, executing commands and more, see [mkpi][].\n* Comment parser for 30+ languages, see [mkparse][].\n* Fast, modular code with good coverage.\n\n---\n\n- [Install](#install)\n- [Features](#features)\n- [Usage](#usage)\n- [Modules](#modules)\n- [Command Line Tools](#command-line-tools)\n  - [mk](#mk)\n  - [mkcat](#mkcat)\n  - [mkpi](#mkpi)\n  - [mkmsg](#mkmsg)\n  - [mkref](#mkref)\n  - [mkabs](#mkabs)\n  - [mkfilter](#mkfilter)\n  - [mklevel](#mklevel)\n  - [mktransform](#mktransform)\n  - [mktoc](#mktoc)\n  - [mkhigh](#mkhigh)\n  - [mkpage](#mkpage)\n  - [mkout](#mkout)\n  - [mkparse](#mkparse)\n  - [mkapi](#mkapi)\n- [API](#api)\n  - [doc](#doc)\n- [License](#license)\n\n---\n\n## Usage\n\nThis example illustrates how to create a readme file like this one from a [source file](https://github.com/mkdoc/mkdoc/blob/master/doc/readme.md) and some [include files](https://github.com/mkdoc/mkdoc/blob/master/doc/readme):\n\n```javascript\nvar doc = require('mkdoc')\n  , pi = require('mkpi')\n  , ref = require('mkref')\n  , abs = require('mkabs')\n  , msg = require('mkmsg')\n  , toc = require('mktoc')\n  , out = require('mkout');\n\ndoc('doc/readme.md')          // read markdown source document\n  .pipe(pi())                 // parse processing instructions, includes etc.\n  .pipe(ref())                // include link references\n  .pipe(abs())                // make links absolute\n  .pipe(msg())                // append generator message\n  .pipe(toc())                // create and inject table of contents list\n  .pipe(out())                // convert abstract syntax tree to markdown\n  .pipe(process.stdout);      // print the document\n```\n\nThe equivalent command line:\n\n```shell\nmkcat doc/readme.md | mkpi | mkref | mkabs | mkmsg | mktoc | mkout\n```\n\nBut the javascript version will be faster as it does not need to launch multiple processes and does not convert the stream to JSON.\n\n## Modules\n\nDesigned to be modular, a brief overview:\n\n* [mktask][] is a streaming build system.\n* [mkcat][] loads source markdown files.\n* [mkast][] is a library for converting tree nodes to JSON.\n* [mkpi][] parses processing instructions and runs macro functions.\n* [mkmsg][] injects a message into a stream.\n* [mkref][] injects link references into a stream.\n* [mkabs][] makes links absolute.\n* [mktoc][] creates a table of contents list.\n* [mkfilter][] removes nodes from the stream by type.\n* [mklevel][] changes heading levels.\n* [mktransform][] add custom stream transformations to the pipeline.\n* [mkout][] renders the tree to an output format (XML, HTML etc).\n* [mkparse][] parses comments from source files.\n* [mkapi][] generates API documentation from comments.\n\n## Command Line Tools\n\n### mk\n\nRuns tasks in build files, by default searches for `mkdoc.js` in the current working directory and parent directories.\n\n```shell\nmk\n```\n\nWhen called with no arguments if a `main` task is available it is invoked otherwise all tasks are executed in sequence.\n\nSpecified tasks are executed in sequence:\n\n```shell\nmk api readme\n```\n\nSee the [mkdoc.js](https://github.com/mkdoc/mkdoc/blob/master/mkdoc.js) file for an example and [mktask][] for information on creating task functions.\n\n[Source Code][mktask] | [CLI Help][mktask help]\n\n### mkcat\n\nReads one or more markdown documents and serializes them to the output stream, this program is normally used at the beginning of a transform pipeline before being sent to `mkout`:\n\n```shell\nmkcat file.md | mkout --xml\n```\n\nIt can also accept input from `stdin`:\n\n```shell\ncat file.md | mkcat | mkout\n```\n\nHowever this is not recommended because file path information is lost which is important for some processing tools such as [mkpi][] which uses the file path to resolve relative include files.\n\n[Source Code][mkcat] | [CLI Help][mkcat help]\n\n### mkpi\n\nInclude markdown documents, source files and the output of commands:\n\n```shell\nmkcat doc/readme.md | mkpi | mkout \u003e README.md\n```\n\nThis program parses and executes processing instructions such as `\u003c? @include intro.md install.md ?\u003e`.\n\nYou can inline macro functions for application-specific logic or create custom macro functions that may be shared between projects, see the [mkpi docs][mkpi] for more details.\n\n[Source Code][mkpi] | [CLI Help][mkpi help]\n\n### mkmsg\n\nAppends or prepends a document to the stream:\n\n```shell\nmkcat doc/readme.md | mkpi | mkmsg | mkout \u003e README.md\n```\n\nTypically used to append a generator message but may be used to inject any document at the beginning or end of the stream.\n\n[Source Code][mkmsg] | [CLI Help][mkmsg help]\n\n### mkref\n\nCollates link references and appends them to the stream.\n\n```shell\nmkcat doc/readme.md | mkpi | mkref | mkout \u003e README.md\n```\n\n[Source Code][mkref] | [CLI Help][mkref help]\n\n### mkabs\n\nMake relative links absolute using the data in `package.json` if no base URL is given.\n\n```shell\nmkcat doc/readme.md | mkpi | mkref | mkabs | mkout \u003e README.md\n```\n\n[Source Code][mkabs] | [CLI Help][mkabs help]\n\n### mkfilter\n\nFilters nodes by type from a stream.\n\nTo remove all headings from a document:\n\n```shell\nmkcat doc/readme.md | mkfilter --heading | mkout\n```\n\nRemove everything but code blocks from a document:\n\n```shell\nmkcat doc/readme.md | mkfilter --code-block --invert | mkout\n```\n\n[Source Code][mkfilter] | [CLI Help][mkfilter help]\n\n### mklevel\n\nConverts heading levels, use this to indent or outdent headings.\n\nTo increment all headings:\n\n```shell\nmkcat README.md | mklevel --all=1 | mkout\n```\n\nTo convert level 3 headings to level 2:\n\n```shell\nmkcat README.md | mklevel -3=-1 | mkout\n```\n\n[Source Code][mklevel] | [CLI Help][mklevel help]\n\n### mktransform\n\nAdd stream classes from files to a pipeline:\n\n```shell\nmkcat README.md | mktransform file.js transformer.js | mkout\n```\n\n[Source Code][mktransform] | [CLI Help][mktransform help]\n\n### mktoc\n\nCreate a standalone table of contents:\n\n```shell\nmkcat README.md | mktoc -s | mkout \u003e TOC.md\n```\n\nInject the table of contents into a document containing the `\u003c!-- @toc --\u003e` marker:\n\n```shell\nmkcat README.md | mktoc | mkout \u003e README.md\n```\n\n[Source Code][mktoc] | [CLI Help][mktoc help]\n\n### mkhigh\n\nHighlight code blocks with ANSI escape characters suitable for printing to a terminal:\n\n```shell\nmkcat README.md | mkhigh -o esc | mkout\n```\n\nGenerate a standalone HTML page with highlighted code blocks converted to `\u003cpre\u003e` elements:\n\n```shell\nmkcat README.md | mkhigh | mkpage | mkhtml \u003e README.html\n```\n\nThis program requires that [source-highlight][] is installed.\n\n[Source Code][mkhigh] | [CLI Help][mkhigh help]\n\n### mkpage\n\nCreate an HTML page:\n\n```shell\nmkcat file.md | mkpage --title=TITLE --style=style.css | mkout --html\n```\n\n[Source Code][mkpage] | [CLI Help][mkpage help]\n\n### mkout\n\nRender a stream to markdown, XML, HTML and JSON.\n\n```shell\nmkcat file.md | mkout --html\n```\n\nThere are also some specialized output programs for certain types that expose more options:\n\n* [mkman](https://github.com/mkdoc/mkout#mkman) - render to man page\n* [mktext](https://github.com/mkdoc/mkout#mktext) - render to plain text\n* [mkhtml](https://github.com/mkdoc/mkout#mkhtml) - render to HTML page\n\n[Source Code][mkout] | [CLI Help][mkout help]\n\n### mkparse\n\nParse comments and tag annotations from source files.\n\n```shell\nmkparse index.js \u003e index.doc.js\n```\n\nLow-level parser for working with comments and tag annotations, see [mkparse][]. The command line interface provides the means to quickly inspect the comments in a document, extract comments to a separate file or strip comments from a document.\n\n[Source Code][mkparse] | [CLI Help][mkparse help]\n\n### mkapi\n\nGenerate API documentation from comments in source files.\n\n```shell\nmkapi index.js lib/*.js --title=API \u003e API.md\n```\n\n[Source Code][mkapi] | [CLI Help][mkapi help]\n\n## API\n\n### doc\n\n```javascript\ndoc(files[, opts])\n```\n\nCreates a stream pipeline using [mkcat][] from the given source files.\n\nRather than an array you can pass file paths in the form:\n\n```javascript\ndoc('intro.md', 'install.md', {});\n```\n\nReturns an output stream.\n\n* `files` Array source markdown files.\n* `opts` Object processing options.\n\n## License\n\nMIT\n\n---\n\nCreated by [mkdoc](https://github.com/mkdoc/mkdoc) on August 3, 2016\n\n[mkcat]: https://github.com/mkdoc/mkcat\n[mkast]: https://github.com/mkdoc/mkast\n[mkfilter]: https://github.com/mkdoc/mkfilter\n[mklevel]: https://github.com/mkdoc/mklevel\n[mktransform]: https://github.com/mkdoc/mktransform\n[mkpi]: https://github.com/mkdoc/mkpi\n[mkmsg]: https://github.com/mkdoc/mkmsg\n[mkref]: https://github.com/mkdoc/mkref\n[mkabs]: https://github.com/mkdoc/mkabs\n[mkpage]: https://github.com/mkdoc/mkpage\n[mkout]: https://github.com/mkdoc/mkout\n[mkparse]: https://github.com/mkdoc/mkparse\n[mkapi]: https://github.com/mkdoc/mkapi\n[mktoc]: https://github.com/mkdoc/mktoc\n[mktask]: https://github.com/mkdoc/mktask\n[mkcat help]: https://github.com/mkdoc/mkcat#help\n[mkfilter help]: https://github.com/mkdoc/mkfilter#help\n[mklevel help]: https://github.com/mkdoc/mklevel#help\n[mktransform help]: https://github.com/mkdoc/mktransform#help\n[mkpi help]: https://github.com/mkdoc/mkpi#help\n[mkmsg help]: https://github.com/mkdoc/mkmsg#help\n[mkref help]: https://github.com/mkdoc/mkref#help\n[mkabs help]: https://github.com/mkdoc/mkabs#help\n[mkpage help]: https://github.com/mkdoc/mkpage#help\n[mkout help]: https://github.com/mkdoc/mkout#help\n[mkparse help]: https://github.com/mkdoc/mkparse#help\n[mkapi help]: https://github.com/mkdoc/mkapi#help\n[mktoc help]: https://github.com/mkdoc/mktoc#help\n[mktask help]: https://github.com/mkdoc/mktask#help\n[mkhigh]: https://github.com/mkdoc/mkhighlight\n[mkhigh help]: https://github.com/mkdoc/mkhighlight#help\n[jshint]: http://jshint.com\n[jscs]: http://jscs.info\n[commonmark]: http://commonmark.org/\n[commonmark.js]: https://github.com/jgm/commonmark.js\n[source-highlight]: https://www.gnu.org/software/src-highlite/source-highlight.html\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkdoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkdoc%2Fmkdoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkdoc/lists"}