{"id":19621333,"url":"https://github.com/commenthol/markedpp","last_synced_at":"2025-04-06T17:11:21.054Z","repository":{"id":20273788,"uuid":"23546920","full_name":"commenthol/markedpp","owner":"commenthol","description":"Preprocessor for markdown files","archived":false,"fork":false,"pushed_at":"2025-02-28T19:32:00.000Z","size":289,"stargazers_count":34,"open_issues_count":1,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T16:11:57.645Z","etag":null,"topics":["autonumber","markdown","preprocessor","table-of-contents","toc"],"latest_commit_sha":null,"homepage":"","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/commenthol.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-09-01T15:23:49.000Z","updated_at":"2025-02-28T19:32:04.000Z","dependencies_parsed_at":"2024-01-28T15:03:49.212Z","dependency_job_id":"cc0c8a14-2c1f-4d4d-9240-1a5bc3545782","html_url":"https://github.com/commenthol/markedpp","commit_stats":{"total_commits":63,"total_committers":2,"mean_commits":31.5,"dds":0.04761904761904767,"last_synced_commit":"5b75064bde0aa32fa9a1bee2f9a0fdc2e2c4b06a"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fmarkedpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fmarkedpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fmarkedpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/commenthol%2Fmarkedpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/commenthol","download_url":"https://codeload.github.com/commenthol/markedpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247517912,"owners_count":20951718,"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":["autonumber","markdown","preprocessor","table-of-contents","toc"],"created_at":"2024-11-11T11:22:24.542Z","updated_at":"2025-04-06T17:11:21.036Z","avatar_url":"https://github.com/commenthol.png","language":"JavaScript","readme":"# markedpp\n\n\u003e Preprocessor for documents written in markdown\n\n[![NPM version](https://badge.fury.io/js/markedpp.svg)](https://www.npmjs.com/package/markedpp/)\n[![Build Status](https://app.travis-ci.com/commenthol/markedpp.svg?branch=master)](https://app.travis-ci.com/commenthol/markedpp)\n\n`markedpp` is a preprocessor for documents written in [markdown][markdown]. The output itself is again markdown.\n\nIt supports the following extensions:\n\n* Generation of a \"Table of Contents\"\n* Automatic numbering of Headings\n* Include various files into a single output document\n* Sorted collection of References\n* Autonumbering of ordered lists\n* Automatic update of heading identifiers\n* Support for autoid for [marked][], [markdown-it][], [unified][], [pandoc][],\n  [github.com][], [gitlab.com][], [bitbucket.org][], [ghost.org][].\n\nThis project is inspired by [markdown-pp][markdown-pp].\nAlbeight the markdown syntax of this project here is slightly different, [markdown-pp][markdown-pp] commands can be used as well.\n\n## Table of Contents\n\n\u003c!-- !numberedheadings (level=4 minlevel=2 skip=1) --\u003e\n\n\u003c!-- !toc (level=4 minlevel=2 omit=\"Table of Contents\") --\u003e\n\n* [1\\. Extended Markdown Syntax](#1-extended-markdown-syntax)\n  * [1.1\\. toc](#11-toc)\n    * [1.1.1\\. level](#111-level)\n    * [1.1.2\\. minlevel](#112-minlevel)\n    * [1.1.3\\. numbered](#113-numbered)\n    * [1.1.4\\. omit](#114-omit)\n  * [1.2\\. ref](#12-ref)\n  * [1.3\\. include](#13-include)\n  * [1.4\\. numberedheadings](#14-numberedheadings)\n    * [1.4.1\\. level](#numberedheadings-level)\n    * [1.4.2\\. minlevel](#142-minlevel)\n    * [1.4.3\\. skip](#143-skip)\n    * [1.4.4\\. start](#144-start)\n    * [1.4.5\\. omit](#145-omit)\n* [2\\. Specials](#2-specials)\n  * [2.1\\. Using custom anchors](#21-using-custom-anchors)\n  * [2.2\\. Changing type of autoId generation](#22-changing-type-of-autoid-generation)\n* [3\\. Installation](#3-installation)\n* [4\\. Usage](#4-usage)\n* [5\\. CLI](#5-cli)\n* [6\\. Running Tests \u0026 Contributing](#6-running-tests--contributing)\n  * [6.1\\. Contribution and License Agreement](#61-contribution-and-license-agreement)\n* [7\\. License](#7-license)\n* [8\\. References](#8-references)\n\n\u003c!-- toc! --\u003e\n\n## 1\\. Extended Markdown Syntax\n\nThe extended markdown syntax for the pre-processor borrows from the already existing image tag.\nAll commands start using a `!` followed by the command. Options for the specific command are specified in normal brackets.\n\n    !\u003ccommand\u003e (\u003coptions\u003e)\n\n\n### 1.1\\. toc\n\n    !toc [([level=1-6] [minlevel=1-6] [numbered] [omit=\"...;...\"])]\n\nInserts a \"Table of Contents\" section:\n\n* level: \\[optional\\] level of headings to show (default is 3)\n* minlevel: \\[optional\\] min-level of headings to show (default is 1)\n* numbered: \\[optional\\] show numbered\n* omit: \\[optional\\] remove headings from ToC. Headings need to be given in `\"` and separated by `;`\n\nE.g.\n\n* [One](#one)\n  * [One One](#one-one)\n    * [One One One](#one-one-one)\n* [Two](#two)\n  * [Two One](#two-one)\n\n    This includes a \"Table of Contents\" section. All headings up to level=3 will be linked with their references as a unnumbered bullet list.\n\nFor compatibility reasons the following alternative syntax is supported:\n\n```\n!TOC\n```\n```\n[[TOC]]\n```\n```\n\u003c!-- toc --\u003e\n\u003c!-- /toc --\u003e\n```\n```\n\u003c!-- toc --\u003e\n\u003c!-- toc stop --\u003e\n```\n```\n\u003c!-- toc --\u003e\n```\n\n#### 1.1.1\\. level\n\n    !toc (level=5)\n\nTo change the default level of 3 to a different one specify the option `level` in brackets.\n\n#### 1.1.2\\. minlevel\n\n    !toc (minlevel=2)\n\nThe option `minlevel` only displays the ToC from `minlevel` leaving out all headings with a lower level.\n\nE.g. with the above example:\n\n* [One One](#one-one)\n  * [One One One](#one-one-one)\n* [Two One](#two-one)\n\n#### 1.1.3\\. numbered\n\n    !toc (numbered)\n\nThe option `numbered` displays the ToC without a bullet list but in a flat numbered fashion\n\nE.g.\n\n1\\. [One](#one) \u003cbr\u003e\n1.1\\. [One One](#one-one) \u003cbr\u003e\n1.1.1\\. [One One One](#one-one-one) \u003cbr\u003e\n2\\. [Two](#two) \u003cbr\u003e\n2.1\\. [Two One](#two-one) \u003cbr\u003e\n\nThe Preprocessor inserts a html comment tag which allows regenerating the TOC on an already preprocessed document.\n\nE.g.\n\n    \u003c!-- !toc (level=1) --\u003e\n\n    * [One](#one)\n    * [Two](#two)\n\n    \u003c!-- toc! --\u003e\n\n#### 1.1.4\\. omit\n\nTo omit headings in the ToC define those with `omit`.\n\nE.g. to remove \"Table of Contents\" and the branch of \"Heading 1\":\n\n    # Table of Contents\n\n    !toc (omit=\"Table of Contents;Heading 1\")\n\n    # Heading 1\n    ## Heading 1.1\n    # Heading 2\n\nwill result in:\n\n    # Table of Contents\n\n    \u003c!-- !toc --\u003e\n\n    * [Heading 2](#heading-2)\n\n    \u003c!-- toc! --\u003e\n\n    # Heading 1\n\n    ## Heading 1.1\n\n    # Heading 2\n\n### 1.2\\. ref\n\n    !ref\n\nThis command includes a references section displaying all references using the alternate link syntax \u003cbr\u003e\n`[\u003cname\u003e]: \u003curl\u003e \"\u003ctitle\u003e\"` given in the document being preprocessed.\n\nLocal references which start with a \"#\" are ignored.\n\nE.g.\n\n    !ref\n\n    [markdown]: http://daringfireball.net/projects/markdown/syntax\n    [GFM]: https://help.github.com/articles/github-flavored-markdown \"Github-Flavored-Markdown\"\n\nrenders as:\n\n    \u003c!-- !ref --\u003e\n\n    * [Github-Flavored-Markdown][GFM]\n    * [markdown][markdown]\n\n    \u003c!-- ref! --\u003e\n\n    [markdown]: http://daringfireball.net/projects/markdown/syntax\n    [GFM]: https://help.github.com/articles/github-flavored-markdown \"Github-Flavored-Markdown\"\n\n### 1.3\\. include\n\n    !include (filename [lang=...] [] [] [] [] [])\n\nThis inserts the the file specified with `filename` at the given position in the document being preprocessed.\nThe preprocessor inserts any type of files.\n\n* filename: \\[mandatory\\] Name of file to include\n* lang: \\[optional\\] language of file - if set, then [GFM][GFM] fences are added around include.\n* indent: \\[optional\\] Indent the included file by `x` spaces\n* start: \\[optional\\] Start including the file from line `x`\n* end: \\[optional\\] End including the file at line `x`\n* link: \\[optional\\] Add a link to this include file with the given label\n* vscode: \\[optional\\] Add a vscode link to this include file with the given label for vscode\n\nTo include a file with specifying the language use the option `lang`.\n\n`start` and `end` will include only the lines from `start` to `end` from the source file. If only `start` is specified, the lines beginning at `start` will be included to the end of the file. If only `end` is specified, the lines from the beginning of the file to `end` will be included.\n\nThe `link` and `vscode` options will add a link in the resulting file that will allow you to open the original file. The text specified in `label` will be the name of the link in the markdown file.  This is useful for including code snippets within the markdown file and still allow navigation to the original source file.\n\nThis then will render using [GFM][GFM] fences.\n\nE.g.\n\n    !include (test.js lang=javascript)\n\nrenders as\n\n    ```javascript\n    /* contents of test.js */\n    ```\n\nFiles to insert which cannot be found or recursive inset of the same file leaves the `!include` command as is.\n\n### 1.4\\. numberedheadings\n\n    !numberedheadings [([level=1-6] [minlevel=1-6] [skip=1..] [start=1..] [omit=\"...;...\"] [skipEscaping])]\n\nAdd numbers on headings\n\n* level: {Number} \\[optional\\] level of Headings to show (default is 3)\n* minlevel: {Number} \\[optional\\] min-level of Headings to show (default is 1)\n* skip: {Number} \\[optional\\] skip number of Headings on min-level\n* start: {Number} \\[optional\\] start numbering of Headings with given number\n* omit: {String} \\[optional\\] omit numbering of Headings. Headings need to be given in `\"` and separated by `;`\n* skipEscaping: \\[optional\\] if enabled `\\` will not escape the last `.` in Headings\n\nAll Headings up to level 3 will get numbered. If used, this command shall be given at the very top of a document.\n\n\u003ca name=\"numberedheadings-level\"\u003e\u003c/a\u003e\n\n#### 1.4.1\\. level\n\nWith the option `level`, the Headings level where the numbering shall be applied, can be specified.\n\nE.g.\n\n    !numberedheadings (level=2)\n\nwill number all Headings of level 1 and 2.\n\nUsed together with `!toc` the numbered Headings with show up numberd in the bullet-list style.\n\nE.g.\n\n* [1\\. One](#1-one)\n  * [1.1\\. One One](#1-1-one-one)\n\n`!toc (numbered)` will display the flat style, still with the numbers.\n\n1\\. [One](#1-one) \u003cbr\u003e\n1.1\\. [One One](#1-1-one-one)\n\n#### 1.4.2\\. minlevel\n\nThe option `minlevel` omits numbering all Headings below `minlevel`.\n\n#### 1.4.3\\. skip\n\nThe option `skip` skips numbering for the first Headings on `minlevel`.\n\n#### 1.4.4\\. start\n\nThe option `start` starts the numbering with the given number.\n\n#### 1.4.5\\. omit\n\nThe option `omit` omits numbering all Headings matching.\n\n## 2\\. Specials\n\n### 2.1\\. Using custom anchors\n\nCustom anchors can be added to headings by putting a `\u003ca name=\"...\"\u003e\u003c/a\u003e` in a separate line right in front of the heading.\n\n```html\n\u003ca name=\"custom-heading\"\u003e\u003c/a\u003e\n# Heading with custom id\n```\n\nInstead of using the auto generated id `#heading-with-custom-id`, `#custom-heading` will be used as anchor in the ToC.\n\n### 2.2\\. Changing type of autoId generation\n\nUnfortunately there is no unique format which defines the composition of an auto identifier in markdown.\n[marked][] uses a different format then github.\n\nAvailable options:\n\n* `--marked`\n  for [marked][] - is default\n* `--markdownit`\n  for [markdown-it][] parser using [markdown-it-anchor][] plugin\n* `--unified`\n  for [unified][] parser using [remark-slug][] plugin\n* `--pandoc`\n  for [pandoc][]\n* `--github`\n  for https://github.com\n* `--gitlab`\n  for https://gitlab.com\n* `--bitbucket`\n  for https://bitbucket.org\n* `--ghost`\n  for https://ghost.org\n\nFor other markdown processors:\n\n* `--autoid`:\n  adds named anchors on headings using `\u003ca name=\"...\"\u003e\u003c/a\u003e`.\n\nOn the CLI\n\n```bash\nmarkedpp --github file.md\n```\n\nOr use in your options\n\n```javascript\nvar markedpp = require('markedpp'),\n    md = '!toc\\n# hello\\n## hello \u0026 again',\n    options = { github: true };\n\nmarkedpp(md, options, function(err, result){\n    console.log(result);\n});\n```\n\n## 3\\. Installation\n\nFor use from commandline consider global install\n\n    npm install -g markedpp\n\nFor your project\n\n    npm install markedpp\n\n## 4\\. Usage\n\n```javascript\nimport { markedpp, markedppAsync } from 'markedpp'\nconst md = '!numberedheadings\\n!toc(level=1)\\n# hello\\n## hello again';\n\nmarkedpp(md, function(err, result){\n    console.log(result);\n    /* Outputs\n    \u003c!-- !numberedheadings --\u003e\n\n    \u003c!-- !toc (level=1) --\u003e\n\n    * [1\\. hello](#1-hello)\n\n    \u003c!-- toc! --\u003e\n\n    # 1\\. hello\n\n    ## 1.1\\. hello again\n    */\n});\n\n// with promises\nconst result = await markedppAsync(md)\n```\n\nTo include files the dirname need to be defined via `options`, otherwise it is assumed that the file to include is relative to the current working directory:\n\n```javascript\n// with commonjs\nconst { markedpp } = require('markedpp')\nconst md = '!include(hello.md)',\nconst options = { dirname: __dirname };\n\nmarkedpp(md, options, function(err, result){\n    console.log(result);\n});\n```\n\n## 5\\. CLI\n\nStandalone\n\n```bash\n$ (cat\u003c\u003cEOF\n!numberedheadings\n!toc(level=1)\n# hello\n## hello again\nEOF\n) \u003e hello.md\n$ markedpp hello.md\n\u003c!-- !numberedheadings --\u003e\n\n\u003c!-- !toc (level=1) --\u003e\n\n* [1\\. hello](#1-hello)\n\n\u003c!-- toc! --\u003e\n\n# 1\\. hello\n\n## 1.1\\. hello again\n```\n\nTogether with [marked][marked]\n\n```bash\n$ markedpp --no-tags hello.md | marked\n\u003cul\u003e\n\u003cli\u003e\u003ca href=\"#1-hello\"\u003e1. hello\u003c/a\u003e\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch1 id=\"1-hello\"\u003e1. hello\u003c/h1\u003e\n\u003ch2 id=\"1-1-hello-again\"\u003e1.1. hello again\u003c/h2\u003e\n```\n\n## 6\\. Running Tests \u0026 Contributing\n\nIf you want to submit a pull request, make sure your changes pass the tests. If you're adding a new feature, be sure to add your own test.\n\nTo run the tests:\n\n```bash\nnpm test\n```\n\n### 6.1\\. Contribution and License Agreement\n\nIf you contribute code to this project, you are implicitly allowing your code\nto be distributed under the MIT license. You are also implicitly verifying that\nall code is your original work.\n\n## 7\\. License\n\nCopyright (c) 2014-, Commenthol. (MIT License)\n\nSee [LICENSE][] for more info.\n\n## 8\\. References\n\n\u003c!-- !ref --\u003e\n\n* [bitbucket.org][bitbucket.org]\n* [ghost.org][ghost.org]\n* [Github-Flavored-Markdown][GFM]\n* [github.com][github.com]\n* [gitlab.com][gitlab.com]\n* [LICENSE][LICENSE]\n* [markdown][markdown]\n* [markdown-it][markdown-it]\n* [markdown-it-anchor][markdown-it-anchor]\n* [markdown-pp][markdown-pp]\n* [marked][marked]\n* [pandoc][pandoc]\n* [remark-slug][remark-slug]\n* [unified][unified]\n\n\u003c!-- ref! --\u003e\n\n[GFM]: https://help.github.com/articles/github-flavored-markdown \"Github-Flavored-Markdown\"\n[LICENSE]: ./LICENSE\n[markdown-it-anchor]: https://npmjs.com/package/markdown-it-anchor\n[markdown-it]: https://npmjs.com/package/markdown-it\n[markdown-pp]: https://github.com/jreese/markdown-pp\n[markdown]: http://daringfireball.net/projects/markdown/syntax\n[marked]: https://npmjs.com/package/marked\n[pandoc]: https://pandoc.org\n[remark-slug]: https://npmjs.com/package/remark-slug\n[unified]: https://npmjs.com/package/unified\n[github.com]: https://github.compare\n[gitlab.com]: https://gitlab.com\n[bitbucket.org]: https://bitbucket.org\n[ghost.org]: https://ghost.org\n","funding_links":[],"categories":["Markdown Building Blocks"],"sub_categories":["Markdown to Markdown Pre-Processor"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommenthol%2Fmarkedpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcommenthol%2Fmarkedpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcommenthol%2Fmarkedpp/lists"}