{"id":19475527,"url":"https://github.com/artdecocode/documentary","last_synced_at":"2025-04-25T14:31:52.581Z","repository":{"id":135404478,"uuid":"137006786","full_name":"artdecocode/documentary","owner":"artdecocode","description":"A Node.js documentation pre-processor to increase productivity.","archived":false,"fork":false,"pushed_at":"2020-02-26T19:11:21.000Z","size":3160,"stargazers_count":8,"open_issues_count":25,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T22:41:33.420Z","etag":null,"topics":["docs","documentation","markdown","node","nodejs","npm","readme"],"latest_commit_sha":null,"homepage":"https://readme.page","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/artdecocode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","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},"funding":{"github":null,"patreon":null,"open_collective":"nodetools","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2018-06-12T02:34:11.000Z","updated_at":"2020-02-26T19:11:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"5fe19129-e57a-45bb-89c0-4d0268626189","html_url":"https://github.com/artdecocode/documentary","commit_stats":null,"previous_names":[],"tags_count":110,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Fdocumentary","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Fdocumentary/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Fdocumentary/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artdecocode%2Fdocumentary/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artdecocode","download_url":"https://codeload.github.com/artdecocode/documentary/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250834065,"owners_count":21494902,"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":["docs","documentation","markdown","node","nodejs","npm","readme"],"created_at":"2024-11-10T19:33:26.114Z","updated_at":"2025-04-25T14:31:52.515Z","avatar_url":"https://github.com/artdecocode.png","language":"JavaScript","funding_links":["https://opencollective.com/nodetools"],"categories":[],"sub_categories":[],"readme":"Documentary\n===\n\n[![npm version](https://badge.fury.io/js/documentary.svg)](https://www.npmjs.com/package/documentary)\n![Node.js CI](https://github.com/artdecocode/documentary/workflows/Node.js%20CI/badge.svg)\n\n\u003ca href=\"https://github.com/artdecocode/documentary\"\u003e\u003cimg src=\"images/LOGO.svg?sanitize=true\" width=\"150\" align=\"left\"\u003e\u003c/a\u003e\n\n_Documentary_ is a command-line tool to manage documentation of _Node.JS_ packages of any size. Due to the fact that there is usually a lot of manual labour involved in creating and keeping up-to-date a README document, such as copying examples and output they produce, there is a need for software that can help automate the process and focus on what is really important, i.e., documenting features. _Documentary_ serves as a pre-processor of documentation and enhances every area of the task of making available high-quality docs for _Node.JS_ (and other languages) packages for fellow developers.\n\n```sh\nyarn add -D documentary\nnpm i documentary --save-dev\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/0.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\nFor example, these are some pieces of documentation infrastructure made available by _Documentary_:\n````html\n\u003c!-- Tables Of Contents --\u003e\n%TOC%\n\n\u003c!-- Examples with paths renaming --\u003e\n%EXAMPLE: example/index.js, ../src =\u003e documentary%\n\n\u003c!-- Forks, native with import/export/jsx --\u003e\n\u003cfork stderr nocache env=\"HELLO=WORLD\"\u003e\n  example/index.js\n\u003c/fork\u003e\n\n\u003c!-- Typedefs with linking --\u003e\n\u003ctypedef narrow flatten\u003e\n  types/index.xml\n\u003c/typedef\u003e\n\n\u003c!-- Methods with custom heading designs --\u003e\n```## runSoftware\n[\n  [\"program\", \"string\"],\n  [\"config=\", \"Object\"]\n]\n```\n\n\u003c!-- Section Breaks --\u003e\n%~ width=\"25\"%\n\n\u003c!-- JSX Components --\u003e\n\u003cmy-component package=\"documentary\"\u003e\n  Checkout https://readme.page\n\u003c/my-component\u003e\n````\nAll of these features come with just 3 transient dependencies in your `node_modules`:\n\n```m\n../documentary-test/node_modules\n├── alamode\n├── documentary\n├── preact\n└── typal\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/1.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd rowspan=\"2\"\u003e\n\n## Table Of Contents\n\n- [Table Of Contents](#table-of-contents)\n- [Wiki](#wiki)\n- [Installation \u0026 Usage](#installation--usage)\n- [Misc](#misc)\n  * [Comments Stripping](#comments-stripping)\n  * [File Splitting](#file-splitting)\n  * [Replacement Rules](#replacement-rules)\n- [CLI](#cli)\n  * [`NODE_DEBUG=doc`](#node_debugdoc)\n  * [Markdown Files](#markdown-files)\n  * [Hidden Files](#hidden-files)\n- [♫ PRO\u003cbr/\u003e♪ Underlined\u003cbr/\u003e♯ `Titles`](#-pro-underlined-titles)\n- [Glossary](#glossary)\n  * [Online Documentation](#online-documentation)\n  * [Editor Documentation](#editor-documentation)\n- [Copyright](#copyright)\n\n\u003c/td\u003e\n\u003c/tr\u003e\u003ctr\u003e\n\u003ctd rowspan=\"2\"\u003e\n\n## Wiki\n\nEach feature of _Documentary_ is described on its relevant Wiki page.\n\n- \u003ckbd\u003e⭐️[Key Features](../../wiki/Key-Features)\u003c/kbd\u003e: A quick overview of the solutions provided by _Documentary_ for developers to make writing documentation a breeze.\n- \u003ckbd\u003e📖[Tables Of Content](../../wiki/Tables-Of-Contents)\u003c/kbd\u003e: Creating a navigation menu for the README page.\n- \u003ckbd\u003e⚜️[Section Breaks](../../wiki/Section-Breaks)\u003c/kbd\u003e: Placing visual separators of sections.\n- \u003ckbd\u003e📐[JSON Tables](../../wiki/JSON-Tables)\u003c/kbd\u003e: Writing _JSON_ array data to be converted into a Markdown table.\n- \u003ckbd\u003e📜[Embed Examples](../../wiki/Embed-Examples)\u003c/kbd\u003e: Decoupling examples from documentation by maintaining separate runnable example file.\n- \u003ckbd\u003e🍴[Forks (Embed Output)](../../wiki/Forks)\u003c/kbd\u003e: Executing examples to show their output, and validating that program works correctly.\n- \u003ckbd\u003e🎩[Method Titles](../../wiki/Method-Titles)\u003c/kbd\u003e: Documenting methods in a standard way, and provide your own designs.\n- \u003ckbd\u003e🎇[JSX Components](../../wiki/JSX-Components)\u003c/kbd\u003e: Implementing custom system-wide and project-scoped components.\n- \u003ckbd\u003e🤖[Macros](../../wiki/Macros)\u003c/kbd\u003e: Constructing patterns to be reused in formation of READMEs.\n- \u003ckbd\u003e☀️[Typedefs](../../wiki/Typedefs)\u003c/kbd\u003e: Display `@typedef` information in _README_ files by maintaining types externally to _JS_ source.\n- \u003ckbd\u003e🎼[Type (Deprecated)](../../wiki/Type-(Deprecated))\u003c/kbd\u003e: An older version of typedefs which works as a macro for types.\n- \u003ckbd\u003e🥠[Gif Detail](../../wiki/Gif-Detail)\u003c/kbd\u003e: Hiding images inside of the `\u003cdetails\u003e` block.\n- \u003ckbd\u003e🖱[API](../../wiki/API)\u003c/kbd\u003e: Using _Documentary_'s features from other packages.\n\n\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/2.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Installation \u0026 Usage\n\nThe `doc` client is available after installation. It can be used in a `doc` script of `package.json`, as follows:\n\n```json\n{\n  \"scripts\": {\n    \"doc\": \"doc documentary -o README.md\"\n  }\n}\n```\n\nThe first argument, `documentary` is a path to a directory containing source documentation files, or a path to a single file to be processed, e.g., `README-source.md`.\n\nTherefore, to produce an output `README.md`, the following command will be used:\n\n```sh\nyarn doc\n```\n\nWhen actively working on documentation, it is possible to use the `watch` mode with `-w` flag, or `-p` flag to also automatically push changes to a remote git repository, merging them into a single commit every time.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/3.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Misc\n\nThese are some essential feature of _Documentary_.\n\n### Comments Stripping\n\nSince comments found in `\u003c!-- comment --\u003e` sections are not visible to users, they will be removed from the compiled output document.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/4.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n### File Splitting\n\n_Documentary_ can read a directory and put files together into a single `README` file. The files will be sorted in alphabetical order, and their content merged into a single stream. The `index.md` and `footer.md` are special in this respect, such that the `index.md` of a directory will always go first, and the `footer.md` will go last. To print in reverse order, for example when writing a blog and name files by their dates, the [`--reverse` flag](#reverse-order) can be passed to the CLI.\n\nExample structure used in this documentation:\n\n```m\ndocumentary\n├── 1-installation-and-usage\n│   └── index.md\n├── 2-features\n│   ├── 4-comment-stripping.md\n│   ├── 5-file-splitting.md\n│   ├── 6-rules.md\n│   └── index.md\n├── 3-cli.md\n├── footer.md\n└── index.md\n```\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/5.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n### Replacement Rules\n\nThere are some other built-in rules for replacements which are listed in this table.\n\n\n|           Rule           |                                                          Description                                                           |\n| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |\n| %NPM: package-name%      | Adds an NPM badge, e.g., `[![npm version] (https://badge.fury.io/js/documentary.svg)] (https://npmjs.org/package/documentary)`                                                               |\n| %TREE directory ...args% | Executes the `tree` command with given arguments. If `tree` is not installed, warns and does not replace the match. |\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/6.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## CLI\n\nThe program is used from the CLI (or `package.json` script).\n\n```sh\ndoc [source] [-o output] [-trwcn] [-p \"commit message\"] [-h1] [-eg] [-vh]\n```\n\nThe arguments it accepts are:\n\n\u003ctable\u003e\n \u003cthead\u003e\n  \u003ctr\u003e\n   \u003cth\u003eArgument\u003c/th\u003e \n   \u003cth\u003eShort\u003c/th\u003e\n   \u003cth\u003eDescription\u003c/th\u003e\n  \u003c/tr\u003e\n \u003c/thead\u003e\n  \u003ctr\u003e\n   \u003ctd\u003esource\u003c/td\u003e\n   \u003ctd\u003e\u003c/td\u003e\n   \u003ctd\u003eThe documentary file or directory to process. Default \u003ccode\u003edocumentary\u003c/code\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--output\u003c/td\u003e\n   \u003ctd\u003e-o\u003c/td\u003e\n   \u003ctd\u003eWhere to save the output (e.g., \u003ccode\u003eREADME.md\u003c/code\u003e).\n    If not passed, prints to \u003ccode\u003estdout\u003c/code\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--wiki\u003c/td\u003e\n   \u003ctd\u003e-W\u003c/td\u003e\n   \u003ctd\u003eGenerate documentation in Wiki mode. The value of the argument must be the location of wiki, e.g., \u003ccode\u003e../documentary.wiki\u003c/code\u003e. The \u003ccode\u003e--output\u003c/code\u003e option in this case has no effect.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--focus\u003c/td\u003e\n   \u003ctd\u003e-f\u003c/td\u003e\n   \u003ctd\u003eWhen generating \u003cem\u003eWiki\u003c/em\u003e, this is a list of comma-separated values that will be converted into RegEx'es used to specify which pages to process in current compilation, e.g., \u003ccode\u003eAddress\u003c/code\u003e, \u003ccode\u003eAddr\u003c/code\u003e or \u003ccode\u003eAddress,DNS\u003c/code\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--toc\u003c/td\u003e\n   \u003ctd\u003e-t\u003c/td\u003e\n   \u003ctd\u003eJust print the table of contents.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--types\u003c/td\u003e\n   \u003ctd\u003e-T\u003c/td\u003e\n   \u003ctd\u003eThe location of types' files which are not referenced in the documentation (e.g., for printing links to external docs).\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--reverse\u003c/td\u003e\n   \u003ctd\u003e-r\u003c/td\u003e\n   \u003ctd\u003ePrint files in reverse order. Useful for blogs.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--h1\u003c/td\u003e\n   \u003ctd\u003e-h1\u003c/td\u003e\n   \u003ctd\u003eAdd \u003ccode\u003eh1\u003c/code\u003e headings to the Table of Contents.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--watch\u003c/td\u003e\n   \u003ctd\u003e-w\u003c/td\u003e\n   \u003ctd\u003eWatch files for changes and recompile the documentation.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--no-cache\u003c/td\u003e\n   \u003ctd\u003e-c\u003c/td\u003e\n   \u003ctd\u003eDisable forks' cache for the run. The new output of\n    forks will be updated in cache so that it can be used\n    next time without \u003ccode\u003e-c\u003c/code\u003e arg.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--namespace\u003c/td\u003e\n   \u003ctd\u003e-n\u003c/td\u003e\n   \u003ctd\u003eThe root namespace: types within it will not be printed\n    with their namespace prefix.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--push\u003c/td\u003e\n   \u003ctd\u003e-p\u003c/td\u003e\n   \u003ctd\u003eStarts \u003cem\u003eDocumentary\u003c/em\u003e in watch mode. After changes are\n    detected, the commit is undone, and new one is made over\n    it, forcing git push.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--debug\u003c/td\u003e\n   \u003ctd\u003e-d\u003c/td\u003e\n   \u003ctd\u003ePrint verbose debug information.\n    Same as setting \u003ccode\u003eNODE_DEBUG=doc\u003c/code\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--annotate\u003c/td\u003e\n   \u003ctd\u003e-a\u003c/td\u003e\n   \u003ctd\u003ePlace resolved URLs to all documented types into the\n    \u003ccode\u003etypedefs.json\u003c/code\u003e file and reference it in \u003ccode\u003epackage.json\u003c/code\u003e.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--generate\u003c/td\u003e\n   \u003ctd\u003e-g\u003c/td\u003e\n   \u003ctd\u003e[Deprecated] Places typedefs definitions into JavaScript\n    files from types.xml. Use \u003ccode\u003etypal\u003c/code\u003e instead.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--extract\u003c/td\u003e\n   \u003ctd\u003e-e\u003c/td\u003e\n   \u003ctd\u003e[Deprecated] Migrates existing typedefs from a JavaScript\n    file into types.xml. Use \u003ccode\u003etypal -m\u003c/code\u003e instead.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--version\u003c/td\u003e\n   \u003ctd\u003e-v\u003c/td\u003e\n   \u003ctd\u003ePrints the current version.\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n   \u003ctd\u003e--help\u003c/td\u003e\n   \u003ctd\u003e-h\u003c/td\u003e\n   \u003ctd\u003eShows the usage information.\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nWhen \u003ca name=\"node_debugdoc\"\u003e`NODE_DEBUG=doc`\u003c/a\u003e is set (or `-d` flag is passed), the program will print processing information, e.g.,\n\n```\nDOC 80734: stripping comment\nDOC 80734: could not parse the table\n```\n\nThis is quite essential to understanding the status of documentation processing, and will be enabled by default in the next version.\n\n### Markdown Files\n\nOnly the following extensions are processed: `markdown`, `md`, `html`, `htm`. Anything else is ignored. This is to allow to place examples in the documentary folder. To process all files, set the `ONLY_DOC=false` variable.\n\n### Hidden Files\n\nHidden files are ignored by default. This can be changed by setting the `DOCUMENTARY_IGNORE_HIDDEN=false` env variable.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/7.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n♫ PRO\n♪ Underlined\n♯ `Titles`\n---\n\nTitles written as blocks and underlined with any number of either `===` (for H1) and `---` (for H2), will be also displayed in the table of contents. However, the actual title will appear on a single line.\n\n```markdown\n♫PRO\n♪Underlined\n♯ `Titles`\n---\n```\n\nAs seen in the [_Markdown Cheatsheet_](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet).\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/8.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Glossary\n\n- **\u003ca name=\"online-documentation\"\u003eOnline Documentation\u003c/a\u003e**: documentation which is accessible online, such as on a GitHub website, or a language reference, e.g., [Node.js Documentation](https://nodejs.org/api/stream.html).\n- **\u003ca name=\"editor-documentation\"\u003eEditor Documentation\u003c/a\u003e**: hints available to the users of an IDE, or an editor, in form of suggestions and descriptive hints on hover over variables' names.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/-3.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e\n\n## Copyright\n\nSection breaks from [FoglihtenDeH0](https://www.1001fonts.com/foglihtendeh0-font.html) font.\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003e\n      \u003ca href=\"https://www.artd.eco\"\u003e\n        \u003cimg width=\"100\" src=\"https://raw.githubusercontent.com/wrote/wrote/master/images/artdeco.png\"\n          alt=\"Art Deco\"\u003e\n      \u003c/a\u003e\n    \u003c/th\u003e\n    \u003cth\u003e© \u003ca href=\"https://www.artd.eco\"\u003eArt Deco™\u003c/a\u003e   2020\u003c/th\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"#table-of-contents\"\u003e\n  \u003cimg src=\"/.documentary/section-breaks/-1.svg?sanitize=true\"\u003e\n\u003c/a\u003e\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartdecocode%2Fdocumentary","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartdecocode%2Fdocumentary","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartdecocode%2Fdocumentary/lists"}