{"id":15481659,"url":"https://github.com/mkdoc/mkout","last_synced_at":"2025-08-04T21:31:06.316Z","repository":{"id":57298825,"uuid":"50490765","full_name":"mkdoc/mkout","owner":"mkdoc","description":"Commonmark output renderers","archived":false,"fork":false,"pushed_at":"2017-02-07T08:21:36.000Z","size":165,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-03T00:43:38.102Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-01-27T07:44:44.000Z","updated_at":"2017-02-06T02:11:20.000Z","dependencies_parsed_at":"2022-08-26T18:02:40.431Z","dependency_job_id":null,"html_url":"https://github.com/mkdoc/mkout","commit_stats":null,"previous_names":["tmpfs/mk3"],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkout","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkout/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkout/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mkdoc%2Fmkout/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mkdoc","download_url":"https://codeload.github.com/mkdoc/mkout/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228679018,"owners_count":17955979,"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":[],"created_at":"2024-10-02T05:05:24.596Z","updated_at":"2024-12-08T01:40:34.420Z","avatar_url":"https://github.com/mkdoc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Renderers\n\n[![Build Status](https://travis-ci.org/mkdoc/mkout.svg?v=3)](https://travis-ci.org/mkdoc/mkout)\n[![npm version](http://img.shields.io/npm/v/mkout.svg?v=3)](https://npmjs.org/package/mkout)\n[![Coverage Status](https://coveralls.io/repos/mkdoc/mkout/badge.svg?branch=master\u0026service=github\u0026v=3)](https://coveralls.io/github/mkdoc/mkout?branch=master)\n\n\u003e Render documents to Markdown, Text, HTML, XML, YAML and JSON\n\nOutput renderers for [commonmark][].\n\n## Install\n\n```\nnpm i mkout --save\n```\n\nFor the command line interface install [mkdoc][] globally (`npm i -g mkdoc`).\n\n---\n\n- [Install](#install)\n- [Usage](#usage)\n- [Example](#example)\n- [Renderer Implementation](#renderer-implementation)\n  - [Markdown](#markdown)\n  - [Text](#text)\n  - [JSON](#json)\n  - [YAML](#yaml)\n- [Help](#help)\n  - [mkman](#mkman)\n  - [mktext](#mktext)\n  - [mkhtml](#mkhtml)\n- [API](#api)\n  - [out](#out)\n    - [Options](#options)\n  - [JsonRenderer](#jsonrenderer)\n    - [Options](#options-1)\n  - [Links](#links)\n  - [.add](#add)\n  - [.list](#list)\n  - [.reset](#reset)\n  - [ManRenderer](#manrenderer)\n    - [Options](#options-2)\n  - [MarkdownRenderer](#markdownrenderer)\n  - [normalize](#normalize)\n  - [TextRenderer](#textrenderer)\n    - [Options](#options-3)\n  - [YamlRenderer](#yamlrenderer)\n    - [Options](#options-4)\n- [License](#license)\n\n---\n\n## Usage\n\nCreate the stream and write a [commonmark][] document:\n\n```javascript\nvar out = require('mkcat')\n  , ast = require('mkast');\nast.src('# Heading')\n  .pipe(out())\n  .pipe(process.stdout);\n```\n\n## Example\n\nPrint as markdown:\n\n```shell\nmkcat README.md | mkout\n```\n\nPrint as HTML:\n\n```shell\nmkcat README.md | mkout --html\n```\n\nPrint as XML:\n\n```shell\nmkcat README.md | mkout --xml\n```\n\nPrint as plain text:\n\n```shell\nmkcat README.md | mkout --text\n```\n\nYAML is particularly useful to get a compact view of the tree:\n\n```shell\nmkcat README.md | mkout -y\n```\n\nFor more detailed YAML use:\n\n```shell\nmkcat README.md | mkout -Y\n```\n\nPrint as JSON:\n\n```shell\nmkcat README.md | mkout -j\n```\n\nPass through the input newline-delimited JSON:\n\n```shell\nmkcat README.md | mkout --noop\n```\n\n## Renderer Implementation\n\nThis section briefly describes the handling of the various [commonmark][] types, see the [api docs](#api) for more detail.\n\n### Markdown\n\nThe markdown renderer renders all basic markdown types as expected however it is not yet [commonmark][] compliant which is work in progress.\n\n### Text\n\nThe text renderer inherits from the markdown renderer so you can choose which types to preserve as markdown, by default headings and lists are preserved. Headings are preserved to maintain the document structure but you may disable them; list rendering is always performed using the underlying markdown renderer.\n\nBlock and inline HTML is normalized to text but may be preserved.\n\nLinks are converted to indexed references in the form `example[1]` and the appropriate references are appended to the document: `[1]:http://example.com`. Duplicate link destinations are resolved.\n\nIf you wanted to preserve some inline elements in addition to headings and lists you could pass the options:\n\n```javascript\n{preserve:{heading: true, code: true, emph: true, strong: true}}\n```\n\nSoft line breaks are removed but you can preserve them. Thematic breaks (`---`) are rendered as a series of 80 hyphens which may be customised.\n\nCode blocks are indented with two spaces, the info string if present is not preserved.\n\n### JSON\n\nThe JSON renderer allows serializing a node tree such that it could be passed between processes or pushed to a remote queue for further processing.\n\nCircular references are resolved and the document has enough information to recreate a node tree with a 1:1 correlation with the original.\n\n### YAML\n\nThe YAML renderer is designed to provide a compact view of the tree which is easy to read but can also include the node properties for an extended view of the document.\n\nWhilst it would be possible to recreate a node tree from a YAML document it is optimized for legibility over processing; use the JSON renderer for serialization requirements.\n\nCompact output for a simple document:\n\n```yaml\n---\n- document: \n  - paragraph: \n    - text: 'Generated by '\n    - link: \n      - text: 'mkdoc'\n---\n```\n\n## Help\n\n```\nUsage: mkout [options]\n\n  Render to various output formats.\n\nOptions\n  -o, --output=[FILE]     Write output to FILE (default: stdout)\n  -H, --html              Set output renderer to HTML\n  -j, --json              Set output renderer to JSON\n  -m, --man               Set output renderer to MAN\n  -t, --text              Set output renderer to TEXT\n  -x, --xml               Set output renderer to XML\n  -y, --yaml              Set output renderer to YAML\n  -Y, --yaml-full         Do not compact YAML output\n  -n, --noop              Pass through input JSON\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmkout@1.0.33\n```\n\n### mkman\n\n```\nUsage: mkman [options]\n\n  Render to troff man page.\n\nOptions\n  -t, --title=[VAL]       Set the page title (default: UNTITLED)\n  -s, --section=[NUM]     Set the section number (default: 1)\n  -i, --inline=[VAL]      Inline code rendering style (default: strong)\n  -l, --locale=[VAL]      Locale for automatic date generation (default: en-gb)\n  -v, --preamble-version=[VAL]     \n                          Version for document preamble (default: 1.0)\n  -d, --date=[VAL]        Use specific date\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmkout@1.0.33\n```\n\n### mktext\n\n```\nUsage: mktext [options]\n\n  Render to plain text.\n\nOptions\n  -i, --indent=[NUM]      Code block and block quote indentation (default: 4)\n  -q, --quote=[VAL]       Character used to prefix block quotes\n  -e, --emph              Preserve emph as markdown\n  -s, --strong            Preserve strong as markdown\n  -c, --code              Preserve inline code as markdown\n  -l, --link              Preserve links as markdown\n  -t, --thematic-break    Preserve thematic break as markdown\n  -I, --image             Preserve image as markdown\n  -C, --code-block        Preserve code block as markdown\n  -B, --block-quote       Preserve block quote as markdown\n  -H, --heading           Preserve heading as markdown\n  -S, --softbreak         Preserve softbreak as markdown\n  -L, --linebreak         Preserve linebreak as markdown\n  --html-inline           Preserve inline html as markdown\n  --html-block            Preserve html block as markdown\n  --custom-inline         Preserve custom inline as markdown\n  --custom-block          Preserve custom block as markdown\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmkout@1.0.33\n```\n\n### mkhtml\n\n```\nUsage: mkhtml [options]\n\n  Render to HTML page.\n\nOptions\n  -h, --help              Display help and exit\n  --version               Print the version and exit\n\nmkout@1.0.33\n```\n\n## API\n\n### out\n\n```javascript\nout([opts][, cb])\n```\n\nPrint via a renderer to an output stream.\n\nReturns an output stream.\n\n* `opts` Object processing options.\n* `cb` Function callback function.\n\n#### Options\n\n* `type` String output type.\n* `input` Readable=process.stdin input stream.\n* `output` Writable=process.stdout output stream.\n* `render` Object renderer options.\n\n### JsonRenderer\n\n```javascript\nnew JsonRenderer([opts])\n```\n\nRenders an abstract syntax tree to JSON.\n\nBy default prints a compact JSON document, pass `indent` for indented\noutput:\n\n```javascript\n{indent: 1}\n```\n\nBut be careful the tree can be very deep so it is not recommended you set\n`indent` to greater than two.\n\n* `opts` Object processing options.\n\n#### Options\n\n* `indent` Number=0 number of spaces to indent the JSON.\n\n### Links\n\n```javascript\nnew Links()\n```\n\nManages a list of links and their destinations in a linked list.\n\nThe `links` array is a list of nodes and `destinations` maps link\ndestinations to their index in the array.\n\n### .add\n\n```javascript\nLinks.prototype.add(node)\n```\n\nAdd a link node to this collection of links.\n\nReturns a boolean indicating whether the link was added.\n\n* `node` Object the link node.\n\n### .list\n\n```javascript\nLinks.prototype.list([newline])\n```\n\nRetrieves a list of link references.\n\nReturns list of link references.\n\n* `newline` String the newline character to use.\n\n### .reset\n\n```javascript\nLinks.prototype.reset()\n```\n\nResets this instance so it does not contain any links.\n\n### ManRenderer\n\n```javascript\nnew ManRenderer([opts])\n```\n\nRenders an abstract syntax tree to a ROFF man page.\n\nThe man page preamble is created using the standard .TH macro and uses\nsensible default values when the corresponding preamble options are not\nspecified.\n\nAdds macros for headings level 1-6 (.h1-.h6), a macro for the thematic\nbreak (.hr) and the newline macro (.nl) after the preamble.\n\nA standard list uses the .BL, .IP and .EL macros rendering a circle as\nthe list bullet.\n\nLists that use the bullet character `+` are treated differently; they are\nrendered using the .TP macro and the first softbreak in the list item\nparagraph causes a newline in the output. This is intended for listing\noptions and commands in the idiomatic format:\n\n```troff\n.TP\n\\fB\\-\\-version\\fR\nPrint version and exit\n```\n\n* `opts` Object processing options.\n\n#### Options\n\n* `autolink` Boolean=true create automatic links by index.\n* `section` String=1 man page section number.\n* `title` String=UNTITLED title for the man page.\n* `preambleVersion` String=1.0 version for the preamble.\n* `description` String description for the preamble.\n* `locale` String locale used for date formatting.\n* `inline` String=emph|strong formatting for inline code.\n* `html` Boolean=false force inclusion of HTML blocks.\n\n### MarkdownRenderer\n\n```javascript\nnew MarkdownRenderer([opts])\n```\n\nRenders an abstract syntax tree to markdown.\n\nEventually the aim is to make the output of this renderer fully\n[commonmark][] compliant, at the moment it's output has not been\ncompletely tested for compliance.\n\n* `opts` Object processing options.\n\n### normalize\n\n```javascript\nnormalize(text)\n```\n\nStrips HTML tags from a string and collapses whitespace similar to how\nXML text nodes are normalized.\n\nThis is designed for the TEXT and MAN output formats so we are not\nconcerned with XSS attacks, use `striptags` or another library if you\nneed to strip tags destined for HTML output.\n\nReturns the normalized text.\n\n* `text` String input text.\n\n### TextRenderer\n\n```javascript\nnew TextRenderer([opts])\n```\n\nRenders an abstract syntax tree to a plain text view.\n\nWith the exception of the PARAGRAPH, LIST and ITEM node types all\nother markdown formatting is removed.\n\nIf you wish to preserve some other aspects of the markdown formatting, you\ncan specify options such as:\n\n```javascript\n{preserve:{emph: true}}\n```\n\nWhich would preserve emphasis as markdown.\n\nCode blocks (when not preserved) are indented by the whitespace specified\nwith the `indent` option, default is four spaces.\n\nBlock quotes are indented according to `indent` and then prefixed with a\nvertical pipe (|), you can change this prefix with the `quote` option.\n\nUnless `autolink` is disabled (or links are preserved) links are\nremoved and appended to the end of the document such that the input:\n\n```markdown\n[Commonmark](http://commonmark.org)\n```\n\nIs converted to:\n\n```\nCommonmark[1]\n\n[1]: http://commomark.org\n```\n\nSoft line breaks are removed unless preserved and a single space is\ninjected when necessary.\n\nThematic breaks are rendered as the hyphen (-) repeated 80 times. You may\nchange this output with the `hr` option.\n\nHTML is normalized to text unless the `html_block` or `html_inline`\nelements are preserved.\n\n* `opts` Object processing options.\n\n#### Options\n\n* `autolink` Boolean=true create automatic links by index.\n* `indent` String amount of whitespace indentation for code blocks.\n* `preserve` Object map of node types that should be preserved.\n\n### YamlRenderer\n\n```javascript\nnew YamlRenderer([opts])\n```\n\nRenders an abstract syntax tree to YAML.\n\nThis implementation is designed to provide an easy to read view of the\ntree; whilst it would certainly be possible to recreate the tree from the\nYAML output it has not been optimized for that use case.\n\nBy default a compact view of the tree is rendered, if you also want to\ninspect the node properties disable `compact`:\n\n```javascript\n{compact: false}\n```\n\n* `opts` Object processing options.\n\n#### Options\n\n* `compact` Boolean=true create compact YAML documents.\n\n## License\n\nMIT\n\n---\n\nCreated by [mkdoc](https://github.com/mkdoc/mkdoc) on April 18, 2016\n\n[mkdoc]: https://github.com/mkdoc/mkdoc\n[node]: http://nodejs.org\n[npm]: http://www.npmjs.org\n[commonmark]: http://commonmark.org\n[jshint]: http://jshint.com\n[jscs]: http://jscs.info\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkout","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmkdoc%2Fmkout","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmkdoc%2Fmkout/lists"}