Repository: remarkjs/remark
Branch: main
Commit: 6c18384e9731
Files: 45
Total size: 129.9 KB
Directory structure:
gitextract_pbroh9s0/
├── .editorconfig
├── .github/
│ └── workflows/
│ ├── bb.yml
│ └── main.yml
├── .gitignore
├── .mailmap
├── .npmrc
├── .prettierignore
├── changelog.md
├── doc/
│ ├── getting-started.md
│ ├── plugins.md
│ └── products.md
├── license
├── package.json
├── packages/
│ ├── remark/
│ │ ├── .npmrc
│ │ ├── index.d.ts
│ │ ├── index.js
│ │ ├── license
│ │ ├── package.json
│ │ ├── readme.md
│ │ └── tsconfig.json
│ ├── remark-cli/
│ │ ├── .npmrc
│ │ ├── cli.js
│ │ ├── license
│ │ ├── package.json
│ │ ├── readme.md
│ │ └── tsconfig.json
│ ├── remark-parse/
│ │ ├── .npmrc
│ │ ├── index.d.ts
│ │ ├── index.js
│ │ ├── lib/
│ │ │ └── index.js
│ │ ├── license
│ │ ├── package.json
│ │ ├── readme.md
│ │ └── tsconfig.json
│ └── remark-stringify/
│ ├── .npmrc
│ ├── index.d.ts
│ ├── index.js
│ ├── lib/
│ │ └── index.js
│ ├── license
│ ├── package.json
│ ├── readme.md
│ └── tsconfig.json
├── readme.md
├── test.js
└── tsconfig.json
================================================
FILE CONTENTS
================================================
================================================
FILE: .editorconfig
================================================
root = true
[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
insert_final_newline = true
trim_trailing_whitespace = true
================================================
FILE: .github/workflows/bb.yml
================================================
jobs:
main:
runs-on: ubuntu-latest
steps:
- uses: unifiedjs/beep-boop-beta@main
with:
repo-token: ${{secrets.GITHUB_TOKEN}}
name: bb
on:
issues:
types: [closed, edited, labeled, opened, reopened, unlabeled]
pull_request_target:
types: [closed, edited, labeled, opened, reopened, unlabeled]
================================================
FILE: .github/workflows/main.yml
================================================
jobs:
canary:
name: canary / ${{matrix.package}}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: node
- run: npm install
- run: npm run build
- uses: actions/checkout@v4
with:
path: canary/${{matrix.package}}
repository: ${{matrix.package}}
- run: |
npm install
for package in $(ls ../../packages); do
npx rimraf "node_modules/**/$package"
done
npm test
working-directory: canary/${{matrix.package}}
strategy:
fail-fast: false
max-parallel: 2
matrix:
package:
- remarkjs/react-markdown
- remarkjs/remark-gfm
main:
name: ${{matrix.node}}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{matrix.node}}
- run: npm install
- run: npm test
- uses: codecov/codecov-action@v5
strategy:
matrix:
node:
- lts/hydrogen
- node
name: main
on:
- pull_request
- push
================================================
FILE: .gitignore
================================================
*.d.ts
*.log
*.map
*.tsbuildinfo
.DS_Store
coverage/
node_modules/
yarn.lock
!/packages/remark-parse/index.d.ts
!/packages/remark-stringify/index.d.ts
!/packages/remark/index.d.ts
================================================
FILE: .mailmap
================================================
Titus Wormer <tituswormer@gmail.com>
Isaac Z. Schlueter <i@izs.me>
Komatsu Seiji <skomatsu.comutt@gmail.com>
Cyril Lakech <cyril.lakech@adeoservices.com>
Zack Bonebrake <info@gigonaut.com>
Omeid Matten <public@omeid.me>
Patrick Bartsch <bartsch98@gmail.com>
Chris Wren <cthewren@gmail.com>
Tsuyusato Kitsune <make.just.on@gmail.com>
Masahiro Miyashiro <3846masahiro+git@gmail.com>
Tom MacWright <tom@macwright.org> Tom MacWright <tmcw@users.noreply.github.com>
Min RK <benjaminrk@gmail.com> MinRK <benjaminrk@gmail.com>
Nick Baugh <niftylettuce@gmail.com>
Alex Leon <alexleon@domain.com.au>
# User names only.
anonymous (Niggler) <foo@bar.org>
anonymous (Mithgol) <getgit@mithgol.ru>
anonymous (insanehong) <intro957@gmail.com>
================================================
FILE: .npmrc
================================================
ignore-scripts=true
package-lock=false
================================================
FILE: .prettierignore
================================================
coverage/
*.md
================================================
FILE: changelog.md
================================================
# Changelog
See [GitHub Releases][releases] for the changelog.
[releases]: https://github.com/remarkjs/remark/releases
================================================
FILE: doc/getting-started.md
================================================
# Getting started
See [the monorepo readme][remark] for what the remark ecosystem is and examples
of how to get started.
[remark]: https://github.com/remarkjs/remark
================================================
FILE: doc/plugins.md
================================================
![remark][file-logo]
# Plugins
**remark** is a tool that transforms markdown with plugins.
See [the monorepo readme][github-remark] for info on what the remark ecosystem
is.
This page lists existing plugins.
## Contents
* [List of plugins](#list-of-plugins)
* [List of utilities](#list-of-utilities)
* [Use plugins](#use-plugins)
* [Create plugins](#create-plugins)
## List of plugins
<a id="list-of-presets"></a>
For the most awesome projects in the ecosystem,
see [`remarkjs/awesome-remark`][github-remark-awesome-remark].
More plugins can be found on GitHub tagged with the
[`remark-plugin` topic][github-topic-remark-plugin].
> 👉 **Note**:
> some plugins don’t work with recent versions of remark due to changes in its
> underlying parser (micromark).
> Plugins that are up to date or unaffected are marked with `🟢` while plugins
> that are **currently broken** are marked with `⚠️`.
> 💡 **Tip**:
> remark plugins work with markdown and **rehype** plugins work with HTML.
> See [*§ List of plugins* in `rehypejs/rehype`][github-rehype-plugins] for more
> plugins.
<!--lint disable media-style-->
The list of plugins:
* [`remark-a11y-emoji`](https://github.com/florianeckerstorfer/remark-a11y-emoji)
— accessible emoji
* ⚠️ [`remark-abbr`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-abbr#readme)
— new syntax for abbreviations (new node type, rehype compatible)
* ⚠️ [`remark-admonitions`](https://github.com/elviswolcott/remark-admonitions)
— new syntax for admonitions
(👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* ⚠️ [`remark-align`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-align#readme)
— new syntax to align text or blocks (new node types, rehype
compatible)
* 🟢 [`remark-api`](https://github.com/wooorm/remark-api)
— generate an API section
* ⚠️ [`remark-attr`](https://github.com/arobase-che/remark-attr)
— new syntax to add attributes to markdown
* 🟢 [`remark-behead`](https://github.com/mrzmmr/remark-behead)
— increase or decrease heading depth
* 🟢 [`remark-breaks`](https://github.com/remarkjs/remark-breaks)
– hard breaks w/o needing spaces (like on issues)
* 🟢 [`remark-capitalize`](https://github.com/zeit/remark-capitalize)
– transform all titles w/ [`title.sh`](https://github.com/zeit/title)
* 🟢 [`remark-capitalize-headings`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-capitalize-headings)
– selectively capitalize headings
(👉 **note**: alternative to [`remark-capitalize`](https://github.com/zeit/remark-capitalize))
* 🟢 [`remark-cite`](https://github.com/benrbray/remark-cite)
– new syntax for Pandoc-style citations
* 🟢 [`remark-cjk-friendly`](https://github.com/tats-u/markdown-cjk-friendly/tree/main/packages/remark-cjk-friendly)
– recognize emphasis in CJK languages more reliably
* 🟢 [`remark-cjk-friendly-gfm-strikethrough`](https://github.com/tats-u/markdown-cjk-friendly/tree/main/packages/remark-cjk-friendly-gfm-strikethrough)
– recognize GFM strikethrough in CJK languages more reliably
* 🟢 [`remark-cloudinary-docusaurus`](https://github.com/johnnyreilly/remark-cloudinary-docusaurus)
– allows Docusaurus to use Cloudinary to serve optimised images
* 🟢 [`remark-code-blocks`](https://github.com/mrzmmr/remark-code-blocks)
— select and store code blocks
* 🟢 [`remark-code-extra`](https://github.com/samlanning/remark-code-extra)
— add to or transform the HTML output of code blocks (rehype compatible)
* 🟢 [`remark-code-frontmatter`](https://github.com/samlanning/remark-code-frontmatter)
— extract frontmatter from code blocks
* 🟢 [`remark-code-import`](https://github.com/kevin940726/remark-code-import)
— populate code blocks from files
* 🟢 [`remark-code-screenshot`](https://github.com/Swizec/remark-code-screenshot)
– turn code blocks into `carbon.now.sh` screenshots
* 🟢 [`remark-code-title`](https://github.com/kevinzunigacuellar/remark-code-title)
— add titles to code blocks
* 🟢 [`remark-codesandbox`](https://github.com/kevin940726/remark-codesandbox)
– create CodeSandbox from code blocks
* 🟢 [`remark-collapse`](https://github.com/Rokt33r/remark-collapse)
— make a section collapsible
* 🟢 [`remark-comment-config`](https://github.com/remarkjs/remark-comment-config)
— configure remark w/ comments
* ⚠️ [`remark-comments`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-comments#readme)
— new syntax to ignore things
* ⚠️ [`remark-container`](https://github.com/zWingz/remark-container)
— new syntax for containers
(👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* ⚠️ [`remark-containers`](https://github.com/Nevenall/remark-containers)
— new syntax for containers
(👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* 🟢 [`remark-contributors`](https://github.com/remarkjs/remark-contributors)
— add a table of contributors
* 🟢 [`remark-copy-linked-files`](https://github.com/sergioramos/remark-copy-linked-files)
— find and copy files linked files to a destination directory
* 🟢 [`remark-corebc`](https://github.com/bchainhub/remark-corebc)
— transforms Core Blockchain notations into markdown links
* 🟢 [`remark-corepass`](https://github.com/bchainhub/remark-corepass)
— transform CorePass notations into markdown links
* ⚠️ [`remark-custom-blocks`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-custom-blocks#readme)
— new syntax for custom blocks (new node types, rehype compatible)
(👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* 🟢 [`remark-custom-header-id`](https://github.com/sindresorhus/remark-custom-header-id)
— add custom ID attribute to headers (`{#some-id}`)
* 🟢 [`remark-definition-list`](https://github.com/wataru-chocola/remark-definition-list)
— support definition lists
* 🟢 [`remark-defsplit`](https://github.com/remarkjs/remark-defsplit)
— change links and images to references w/ separate definitions
* ⚠️ [`remark-disable-tokenizers`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-disable-tokenizers#readme)
— turn some or all remark’s tokenizers on or off
* 🟢 [`remark-directive`](https://github.com/remarkjs/remark-directive)
— new syntax for directives (generic extensions)
* 🟢 [`remark-directive-rehype`](https://github.com/IGassmann/remark-directive-rehype)
— turn [directives][github-remark-directive] into HTML custom elements
(rehype compatible)
* 🟢 [`remark-directive-sugar`](https://github.com/lin-stephanie/remark-directive-sugar)
— predefined directives for customizable badges, links, video embeds, and more
* 🟢 [`remark-docx`](https://github.com/inokawa/remark-docx)
— compile markdown to docx
* 🟢 [`@m2d/remark-docx`](https://github.com/md2docx/remark-docx)
— compile markdown to docx with support for GFM, tables, html, and more.
* 🟢 [`remark-dropcap`](https://github.com/brev/remark-dropcap)
— fancy and accessible drop caps
* 🟢 [`remark-embed-images`](https://github.com/remarkjs/remark-embed-images)
— embed local images as base64-encoded data URIs
* 🟢 [`remark-emoji`](https://github.com/rhysd/remark-emoji)
— transform Gemoji short-codes to emoji
* 🟢 [`remark-extended-table`](https://github.com/wataru-chocola/remark-extended-table)
— extended table syntax allowing colspan / rowspan
* 🟢 [`remark-extract-frontmatter`](https://github.com/mrzmmr/remark-extract-frontmatter)
— store front matter in vfiles
* 🟢 [`remark-fediverse-user`](https://github.com/bchainhub/remark-fediverse-user)
— transform Fediverse user notations into markdown links
* 🟢 [`remark-first-heading`](https://github.com/laat/remark-first-heading)
— change the first heading in a document
* 🟢 [`remark-fix-guillemets`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-fix-guillemets#readme)
— support ASCII guillements (`<<`, `>>`) mapping them to HTML
* 🟢 [`remark-flexible-code-titles`](https://github.com/ipikuka/remark-flexible-code-titles)
— add titles or/and containers for code blocks with customizable attributes
* 🟢 [`remark-flexible-containers`](https://github.com/ipikuka/remark-flexible-containers)
— add custom/flexible containers with customizable properties
* 🟢 [`remark-flexible-markers`](https://github.com/ipikuka/remark-flexible-markers)
— add custom/flexible mark element with customizable properties
* 🟢 [`remark-flexible-paragraphs`](https://github.com/ipikuka/remark-flexible-paragraphs)
— add custom/flexible paragraphs with customizable properties
* 🟢 [`remark-flexible-toc`](https://github.com/ipikuka/remark-flexible-toc)
— expose the table of contents (toc) via Vfile.data or an option reference
* 🟢 [`remark-footnotes-extra`](https://github.com/miaobuao/remark-footnotes-extra)
— add footnotes via short syntax
* 🟢 [`remark-frontmatter`](https://github.com/remarkjs/remark-frontmatter)
– support frontmatter (yaml, toml, and more)
* 🟢 [`remark-gemoji`](https://github.com/remarkjs/remark-gemoji)
— better support for Gemoji shortcodes
* ⚠️ [`remark-generic-extensions`](https://github.com/medfreeman/remark-generic-extensions)
— new syntax for the CommonMark generic directive extension
(👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* 🟢 [`remark-gfm`](https://github.com/remarkjs/remark-gfm)
— support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists)
* 🟢 [`remark-git-contributors`](https://github.com/remarkjs/remark-git-contributors)
— add a table of contributors based on Git history, options, and more
* 🟢 [`remark-github`](https://github.com/remarkjs/remark-github)
— autolink references to commits, issues, pull-requests, and users
* 🟢 [`remark-github-admonitions-to-directives`](https://github.com/incentro-dc/remark-github-admonitions-to-directives)
— convert GitHub’s blockquote-based admonitions syntax to directives syntax
* 🟢 [`remark-github-beta-blockquote-admonitions`](https://github.com/myl7/remark-github-beta-blockquote-admonitions)
— [GitHub beta blockquote-based admonitions](https://github.com/github/feedback/discussions/16925)
* 🟢 [`remark-github-blockquote-alert`](https://github.com/jaywcjlove/remark-github-blockquote-alert)
— remark plugin to add support for [GitHub Alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)
* ⚠️ [`remark-grid-tables`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-grid-tables#readme)
— new syntax to describe tables (rehype compatible)
* 🟢 [`@adobe/remark-grid-tables`](https://github.com/adobe/remark-gridtables)
— pandoc compatible grid-table syntax
* 🟢 [`remark-heading-id`](https://github.com/imcuttle/remark-heading-id)
— custom heading id support `{#custom-id}`
* 🟢 [`remark-heading-gap`](https://github.com/remarkjs/remark-heading-gap)
— serialize w/ more blank lines between headings
* 🟢 [`@vcarl/remark-headings`](https://github.com/vcarl/remark-headings)
— extract a list of headings as data
* 🟢 [`remark-hexo`](https://github.com/bennycode/remark-hexo)
— renders [Hexo tags](https://hexo.io/docs/tag-plugins)
* 🟢 [`remark-highlight.js`](https://github.com/remarkjs/remark-highlight.js)
— highlight code blocks w/
[`highlight.js`](https://github.com/isagalaev/highlight.js)
(rehype compatible)
* 🟢 [`remark-hint`](https://github.com/sergioramos/remark-hint)
— add hints/tips/warnings to markdown
* 🟢 [`remark-html`](https://github.com/remarkjs/remark-html)
— serialize markdown as HTML
* ⚠️ [`remark-iframes`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-iframes#readme)
— new syntax to create iframes (new node type, rehype compatible)
* 🟢 [`remark-ignore`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-ignore)
— use comments to exclude nodes from transformation
* 🟢 [`remark-images`](https://github.com/remarkjs/remark-images)
— add an improved image syntax
* 🟢 [`remark-img-links`](https://github.com/Pondorasti/remark-img-links)
— prefix relative image paths with an absolute URL
* 🟢 [`@it-service-npm/remark-include`](https://github.com/IT-Service-NPM/remark-include)
— add `::include{file=path.md}` statements to compose markdown files together
* 🟢 [`remark-inline-links`](https://github.com/remarkjs/remark-inline-links)
— change references and definitions to links and images
* 🟢 [`remark-ins`](https://github.com/ipikuka/remark-ins)
— add ins element for inserted texts opposite to deleted texts
* 🟢 [`remark-join-cjk-lines`](https://github.com/purefun/remark-join-cjk-lines)
— remove extra space between CJK Characters.
* ⚠️ [`remark-kbd`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-kbd#readme)
— new syntax for keyboard keys (new node type, rehype compatible)
* ⚠️ [`remark-kbd-plus`](https://github.com/twardoch/remark-kbd-plus)
— new syntax for keyboard keys w/ plusses (new node type, rehype
compatible)
* 🟢 [`remark-license`](https://github.com/remarkjs/remark-license)
— add a license section
* 🟢 [`remark-link-rewrite`](https://github.com/rjanjic/remark-link-rewrite)
— customize link URLs dynamically
* 🟢 [`remark-linkify-regex`](https://gitlab.com/staltz/remark-linkify-regex)
— change text matching a regex to links
* 🟢 [`remark-lint`](https://github.com/remarkjs/remark-lint)
— check markdown code style
* 🟢 [`remark-man`](https://github.com/remarkjs/remark-man)
— serialize markdown as man pages (roff)
* 🟢 [`remark-math`](https://github.com/remarkjs/remark-math)
— new syntax for math (new node types, rehype compatible)
* 🟢 [`remark-mdx`](https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx)
— support MDX (JSX, expressions, ESM)
* 🟢 [`remark-mentions`](https://github.com/FinnRG/remark-mentions)
— replace @ mentions with links
* 🟢 [`remark-merge-data`](https://github.com/s-h-a-d-o-w/remark-merge-data)
— merge globally defined data with data declared across code blocks
* 🟢 [`remark-mermaidjs`](https://github.com/remcohaszing/remark-mermaidjs)
— transform mermaid code blocks into inline SVGs
* 🟢 [`remark-message-control`](https://github.com/remarkjs/remark-message-control)
— turn some or all messages on or off
* 🟢 [`remark-normalize-headings`](https://github.com/remarkjs/remark-normalize-headings)
— make sure at most one top-level heading exists
* 🟢 [`remark-numbered-footnote-labels`](https://github.com/jackfletch/remark-numbered-footnote-labels)
— label footnotes w/ numbers
* 🟢 [`@agentofuser/remark-oembed`](https://github.com/agentofuser/remark-oembed)
— transform URLs for youtube, twitter, etc. embeds
* 🟢 [`remark-oembed`](https://github.com/sergioramos/remark-oembed)
— transform URLs surrounded by newlines into *asynchronously* loading
embeds
* 🟢 [`remark-package-dependencies`](https://github.com/unlight/remark-package-dependencies)
— inject your dependencies
* ⚠️ [`remark-parse-yaml`](https://github.com/landakram/remark-parse-yaml)
— parse YAML nodes and expose their value as `parsedValue`
* 🟢 [`remark-pdf`](https://github.com/inokawa/remark-pdf)
— compile markdown to pdf
* ⚠️ [`remark-ping`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-ping#readme)
— new syntax for mentions w/ configurable existence check (new node
type, rehype compatible)
* 🟢 [`remark-plugin-autonbsp`](https://github.com/denisinvader/remark-plugin-autonbsp)
— replace whitespace with non-breaking spaces
to avoid hanging articles, prepositions and digits
* 🟢 [`remark-prepend-url`](https://github.com/alxjpzmn/remark-prepend-url)
— prepend an absolute url to relative links
* 🟢 [`remark-prettier`](https://github.com/remcohaszing/remark-prettier)
— check and format markdown using Prettier
* 🟢 [`remark-prism`](https://github.com/sergioramos/remark-prism)
— highlight code blocks w/ [Prism](https://prismjs.com/) (supporting most
Prism plugins)
* 🟢 [`@handlewithcare/remark-prosemirror`](https://github.com/handlewithcarecollective/remark-prosemirror)
— compile markdown to [ProseMirror](https://prosemirror.net/) documents
* ⚠️ [`remark-redact`](https://github.com/seafoam6/remark-redact)
— new syntax to conceal text matching a regex
* 🟢 [`remark-redactable`](https://github.com/code-dot-org/remark-redactable)
— write plugins to redact content from a markdown document,
then restore it later
* 🟢 [`remark-refer-plantuml`](https://github.com/PrinOrange/remark-refer-plantuml)
— automatically transform PlantUML code into referenced embeddable image URLs
* 🟢 [`remark-reference-links`](https://github.com/remarkjs/remark-reference-links)
— transform links and images into references and definitions
* 🟢 [`remark-rehype`](https://github.com/remarkjs/remark-rehype)
— transform to [rehype](https://github.com/rehypejs/rehype)
* 🟢 [`remark-relative-links`](https://github.com/zslabs/remark-relative-links)
— change absolute URLs to relative ones
* 🟢 [`remark-remove-comments`](https://github.com/alvinometric/remark-remove-comments)
— remove HTML comments from the processed output
* 🟢 [`remark-remove-unused-definitions`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-remove-unused-definitions)
— remove unused reference-style link definitions
* 🟢 [`remark-remove-url-trailing-slash`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-remove-url-trailing-slash)
— remove trailing slashes from the ends of all URL paths
* 🟢 [`remark-renumber-references`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-renumber-references)
— renumber numeric reference-style link ids contiguously starting from 1
* 🟢 [`remark-retext`](https://github.com/remarkjs/remark-retext)
— transform to [retext](https://github.com/retextjs/retext)
* 🟢 [`remark-ruby`](https://github.com/laysent/remark-ruby)
— new syntax for ruby (furigana)
* 🟢 [`remark-sectionize`](https://github.com/jake-low/remark-sectionize)
— wrap headings and subsequent content in section tags (new node type,
rehype compatible)
* ⚠️ [`remark-shortcodes`](https://github.com/djm/remark-shortcodes)
— new syntax for Wordpress- and Hugo-like shortcodes (new node type)
(👉 **note**: [`remark-directive`][github-remark-directive] is similar and up
to date)
* 🟢 [`remark-simple-plantuml`](https://github.com/akebifiky/remark-simple-plantuml)
— turn PlantUML code blocks to images
* 🟢 [`remark-slate`](https://github.com/hanford/remark-slate)
— compile markdown to [Slate nodes](https://docs.slatejs.org/concepts/02-nodes)
* 🟢 [`remark-slate-transformer`](https://github.com/inokawa/remark-slate-transformer)
— compile markdown to
[Slate nodes](https://docs.slatejs.org/concepts/02-nodes)
and Slate nodes to markdown
* 🟢 [`remark-smartypants`](https://github.com/silvenon/remark-smartypants)
— SmartyPants
* 🟢 [`remark-smcat`](https://github.com/shedali/remark-smcat)
— state machine cat
* 🟢 [`remark-sort-definitions`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-sort-definitions)
— reorder reference-style link definitions
* 🟢 [`remark-sources`](https://github.com/unlight/remark-sources)
— insert source code
* 🟢 [`remark-strip-badges`](https://github.com/remarkjs/remark-strip-badges)
— remove badges (such as `shields.io`)
* 🟢 [`remark-strip-html`](https://github.com/craftzdog/remark-strip-html)
— remove HTML
* 🟢 [`remark-squeeze-paragraphs`](https://github.com/remarkjs/remark-squeeze-paragraphs)
— remove empty paragraphs
* ⚠️ [`remark-sub-super`](https://github.com/zestedesavoir/zmarkdown/tree/HEAD/packages/remark-sub-super)
— new syntax for super- and subscript (new node types, rehype
compatible)
* ⚠️ [`remark-terms`](https://github.com/Nevenall/remark-terms)
— new customizable syntax for special terms and phrases
* 🟢 [`remark-textr`](https://github.com/remarkjs/remark-textr)
— transform text w/ [`Textr`](https://github.com/shuvalov-anton/textr)
* 🟢 [`remark-tight-comments`](https://github.com/Xunnamius/unified-utils/blob/main/packages/remark-tight-comments)
— selectively remove newlines around comments
* 🟢 [`remark-title`](https://github.com/RichardLitt/remark-title)
— check and add the document title
* 🟢 [`remark-toc`](https://github.com/remarkjs/remark-toc)
— add a table of contents
* 🟢 [`remark-torchlight`](https://github.com/torchlight-api/remark-torchlight)
— syntax highlighting powered by [torchlight.dev](https://torchlight.dev)
* 🟢 [`remark-tree-sitter`](https://github.com/samlanning/remark-tree-sitter)
— highlight code blocks in markdown files using
[Tree-sitter](https://tree-sitter.github.io/tree-sitter/)
(rehype compatible)
* 🟢 [`remark-truncate-links`](https://github.com/GaiAma/Coding4GaiAma/tree/HEAD/packages/remark-truncate-links)
— truncate/shorten urls not manually named
* 🟢 [`remark-twemoji`](https://github.com/madiodio/remark-twemoji)
— turn emoji into [Twemoji](https://github.com/twitter/twemoji)
* 🟢 [`remark-typedoc-symbol-links`](https://github.com/kamranayub/remark-typedoc-symbol-links)
— turn Typedoc symbol link expressions into markdown links
* 🟢 [`remark-typescript`](https://github.com/trevorblades/remark-typescript)
— turn TypeScript code to JavaScript
* 🟢 [`remark-typograf`](https://github.com/mavrin/remark-typograf)
— transform text w/ [Typograf](https://github.com/typograf)
* 🟢 [`remark-unlink`](https://github.com/remarkjs/remark-unlink)
— remove all links, references, and definitions
* 🟢 [`remark-usage`](https://github.com/remarkjs/remark-usage)
— add a usage example
* 🟢 [`remark-utf8`](https://github.com/Swizec/remark-utf8)
— turn bolds, italics, and code into UTF 8 special characters
* 🟢 [`remark-validate-links`](https://github.com/remarkjs/remark-validate-links)
— check links to headings and files
* ⚠️ [`remark-variables`](https://github.com/mrzmmr/remark-variables)
— new syntax for variables
* 🟢 [`remark-vdom`](https://github.com/remarkjs/remark-vdom)
— compile markdown to [VDOM](https://github.com/Matt-Esch/virtual-dom/)
* 🟢 [`remark-wiki-link`](https://github.com/landakram/remark-wiki-link)
— new syntax for wiki links (rehype compatible)
* 🟢 [`remark-yaml-config`](https://github.com/remarkjs/remark-yaml-config)
— configure remark w/ YAML
<!--lint enable media-style-->
## List of utilities
For things that work with the syntax tree used in remark for markdown,
see [*§ List of utilities* in `syntax-tree/mdast`][github-mdast-utilities].
For tools that work with **mdast** and other syntax trees,
see [*§ List of utilities* in `syntax-tree/unist`][github-unist-utilities].
For tools that work with the virtual file format used in remark,
see [*§ List of utilities* in `vfile/vfile`][github-vfile-utilities].
## Use plugins
To use a plugin programmatically (from JavaScript),
call the [`use()`][github-unified-use] method.
To use plugin with `remark-cli` (from the terminal),
pass a [`--use` flag][github-unified-args-use] or
specify it in a
[configuration file][github-unified-engine-config-files].
## Create plugins
To create a plugin,
first read up on what they are in
[*§ Plugin* in `unifiedjs/unified`][github-unified-plugin].
After that read
[*§ Create a remark plugin* on `unifiedjs.com`][unifiedjs-create-a-plugin]
for a practical introduction.
Finally take one of the existing plugins,
which looks similar to what you’re about to make,
and work from there.
If you get stuck,
[discussions][health-discussions] is a good place to get help.
You should pick a name prefixed by `remark-` (such as `remark-lint`).
**Do not use the `remark-` prefix** if the thing you create doesn’t work with
`remark().use()`:
it isn’t a “plugin” and will confuse users.
If it works with mdast use `mdast-util-`.
If it works with any unist tree use `unist-util-`.
If it works with virtual files use `vfile-`.
Use default exports to expose plugins from your packages.
Add `remark-plugin` keywords in `package.json`.
Add a `remark-plugin` topic to your repo on GitHub.
Create a pull request to add the plugin here on this page!
[file-logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true
[github-mdast-utilities]: https://github.com/syntax-tree/mdast#list-of-utilities
[github-rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins
[github-remark]: https://github.com/remarkjs/remark
[github-remark-awesome-remark]: https://github.com/remarkjs/awesome-remark
[github-remark-directive]: https://github.com/remarkjs/remark-directive
[github-topic-remark-plugin]: https://github.com/topics/remark-plugin
[github-unified-args-use]: https://github.com/unifiedjs/unified-args#--use-plugin
[github-unified-engine-config-files]: https://github.com/unifiedjs/unified-engine#config-files
[github-unified-plugin]: https://github.com/unifiedjs/unified#plugin
[github-unified-use]: https://github.com/unifiedjs/unified#processoruseplugin-options
[github-unist-utilities]: https://github.com/syntax-tree/unist#unist-utilities
[github-vfile-utilities]: https://github.com/vfile/vfile#list-of-utilities
[health-discussions]: https://github.com/remarkjs/remark/discussions
[unifiedjs-create-a-plugin]: https://unifiedjs.com/learn/guide/create-a-remark-plugin/
================================================
FILE: doc/products.md
================================================
# Products
See [awesome remark][awesome] for the products using remark.
[awesome]: https://github.com/remarkjs/awesome
================================================
FILE: license
================================================
(The MIT License)
Copyright (c) Titus Wormer <tituswormer@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
================================================
FILE: package.json
================================================
{
"name": "remark",
"private": true,
"license": "MIT",
"homepage": "https://remark.js.org",
"repository": "https://github.com/remarkjs/remark",
"bugs": "https://github.com/remarkjs/remark/issues",
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
},
"type": "module",
"workspaces": [
"packages/remark-parse/",
"packages/remark-stringify/",
"packages/remark/",
"packages/remark-cli/"
],
"devDependencies": {
"@types/mdast": "^4.0.0",
"@types/node": "^22.0.0",
"c8": "^10.0.0",
"mdast-util-gfm": "^3.0.0",
"micromark-extension-gfm": "^3.0.0",
"prettier": "^3.0.0",
"remark-preset-wooorm": "^11.0.0",
"type-coverage": "^2.0.0",
"typescript": "^5.0.0",
"unified": "^11.0.0",
"unist-util-remove-position": "^5.0.0",
"xo": "^0.60.0"
},
"scripts": {
"build": "tsc --build --clean && tsc --build && type-coverage",
"format": "./packages/remark-cli/cli.js --frail --output --quiet -- . && prettier --log-level warn --write -- . && xo --fix",
"test-api": "node --conditions development test.js",
"test-coverage": "c8 --100 --reporter lcov -- npm run test-api",
"test": "npm run build && npm run format && npm run test-coverage"
},
"prettier": {
"bracketSpacing": false,
"singleQuote": true,
"semi": false,
"tabWidth": 2,
"trailingComma": "none",
"useTabs": false
},
"remarkConfig": {
"plugins": [
"remark-preset-wooorm",
[
"remark-lint-no-html",
false
]
]
},
"typeCoverage": {
"atLeast": 100,
"strict": true
},
"xo": {
"prettier": true,
"rules": {
"unicorn/prefer-string-replace-all": "off"
}
}
}
================================================
FILE: packages/remark/.npmrc
================================================
ignore-scripts=true
package-lock=false
================================================
FILE: packages/remark/index.d.ts
================================================
/// <reference types="remark-parse" />
/// <reference types="remark-stringify" />
import type {Root} from 'mdast'
import type {Processor} from 'unified'
/**
* Create a new unified processor that already uses `remark-parse` and
* `remark-stringify`.
*/
export const remark: Processor<Root, undefined, undefined, Root, string>
================================================
FILE: packages/remark/index.js
================================================
// Note: types exposed from `index.d.ts`
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
/**
* Create a new unified processor that already uses `remark-parse` and
* `remark-stringify`.
*/
export const remark = unified().use(remarkParse).use(remarkStringify).freeze()
================================================
FILE: packages/remark/license
================================================
(The MIT License)
Copyright (c) Titus Wormer <tituswormer@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
================================================
FILE: packages/remark/package.json
================================================
{
"author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
"bugs": "https://github.com/remarkjs/remark/issues",
"contributors": [
"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
],
"dependencies": {
"@types/mdast": "^4.0.0",
"remark-parse": "^11.0.0",
"remark-stringify": "^11.0.0",
"unified": "^11.0.0"
},
"description": "markdown processor powered by plugins part of the unified collective",
"exports": "./index.js",
"files": [
"index.d.ts",
"index.js"
],
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
},
"homepage": "https://remark.js.org",
"keywords": [
"abstract",
"ast",
"compile",
"markdown",
"mdast",
"parse",
"process",
"remark",
"serialize",
"stringify",
"syntax",
"tree",
"unified"
],
"license": "MIT",
"name": "remark",
"repository": "https://github.com/remarkjs/remark/tree/main/packages/remark",
"scripts": {},
"sideEffects": false,
"typeCoverage": {
"atLeast": 100,
"strict": true
},
"type": "module",
"version": "15.0.1",
"xo": {
"overrides": [
{
"files": [
"**/*.d.ts"
],
"rules": {
"@typescript-eslint/triple-slash-reference": "off"
}
}
],
"prettier": true
}
}
================================================
FILE: packages/remark/readme.md
================================================
# remark
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
**[unified][github-unified]** processor with support for parsing from markdown
and serializing to markdown.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`remark()`](#remark-1)
* [Examples](#examples)
* [Example: checking markdown](#example-checking-markdown)
* [Example: passing options to `remark-stringify`](#example-passing-options-to-remark-stringify)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
This package is a [unified][github-unified] processor with support for parsing
markdown as input and serializing markdown as output by using unified with
[`remark-parse`][github-remark-parse] and
[`remark-stringify`][github-remark-stringify].
See [the monorepo readme][github-remark] for info on what the remark ecosystem
is.
## When should I use this?
You can use this package when you want to use unified,
have markdown as input,
and want markdown as output.
This package is a shortcut for
`unified().use(remarkParse).use(remarkStringify)`.
When the input isn’t markdown (meaning you don’t need `remark-parse`) or the
output is not markdown (you don’t need `remark-stringify`),
it’s recommended to use `unified` directly.
When you want to inspect and format markdown files in a project on the command
line,
you can use [`remark-cli`][github-remark-cli].
## Install
This package is [ESM only][esm].
In Node.js (version 16+),
install with [npm][npm-install]:
```sh
npm install remark
```
In Deno with [`esm.sh`][esmsh]:
```js
import {remark} from 'https://esm.sh/remark@15'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import {remark} from 'https://esm.sh/remark@15?bundle'
</script>
```
## Use
Say we have the following module `example.js`:
```js
import {remark} from 'remark'
import remarkToc from 'remark-toc'
const value = `
# Pluto
Pluto is a dwarf planet in the Kuiper belt.
## Contents
## History
### Discovery
In the 1840s, Urbain Le Verrier used Newtonian mechanics to predict the position of…
### Name and symbol
The name Pluto is for the Roman god of the underworld, from a Greek epithet for Hades…
### Planet X disproved
Once Pluto was found, its faintness and lack of a viewable disc cast doubt…
## Orbit
Pluto's orbital period is about 248 years…
`
const file = await remark().use(remarkToc).process(value)
console.error(String(file))
```
…running that with `node example.js` yields:
```markdown
# Pluto
Pluto is a dwarf planet in the Kuiper belt.
## Contents
* [History](#history)
* [Discovery](#discovery)
* [Name and symbol](#name-and-symbol)
* [Planet X disproved](#planet-x-disproved)
* [Orbit](#orbit)
## History
### Discovery
In the 1840s, Urbain Le Verrier used Newtonian mechanics to predict the position of…
### Name and symbol
The name Pluto is for the Roman god of the underworld, from a Greek epithet for Hades…
### Planet X disproved
Once Pluto was found, its faintness and lack of a viewable disc cast doubt…
## Orbit
Pluto's orbital period is about 248 years…
```
## API
This package exports the identifier [`remark`][api-remark].
There is no default export.
### `remark()`
Create a new unified processor that already uses
[`remark-parse`][github-remark-parse] and
[`remark-stringify`][github-remark-stringify].
You can add more plugins with `use`.
See [`unified`][github-unified] for more information.
## Examples
### Example: checking markdown
The following example checks that markdown code style is consistent and follows
some best practices:
```js
import {remark} from 'remark'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import {reporter} from 'vfile-reporter'
const file = await remark()
.use(remarkPresetLintConsistent)
.use(remarkPresetLintRecommended)
.process('1) Hello, _Jupiter_ and *Neptune*!')
console.error(reporter(file))
```
Yields:
```text
1:2 warning Unexpected ordered list marker `)`, expected `.` ordered-list-marker-style remark-lint
1:25-1:34 warning Unexpected emphasis marker `*`, expected `_` emphasis-marker remark-lint
[cause]:
1:11-1:20 info Emphasis marker style `'_'` first defined for `'consistent'` here emphasis-marker remark-lint
1:35 warning Unexpected missing final newline character, expected line feed (`\n`) at end of file final-newline remark-lint
⚠ 3 warnings
```
### Example: passing options to `remark-stringify`
When you use `remark-stringify` manually you can pass options to `use`.
Because `remark-stringify` is already used in `remark` that’s not possible.
To define options for `remark-stringify`,
you can instead pass options to `data`:
```js
import {remark} from 'remark'
const value = `
# Moons of Neptune
1. Naiad
2. Thalassa
3. Despine
4. …
`
const file = await remark()
.data('settings', {
bulletOrdered: ')',
incrementListMarker: false,
setext: true
})
.process(value)
console.log(String(file))
```
Yields:
```markdown
Moons of Neptune
================
1) Naiad
1) Thalassa
1) Despine
1) …
```
## Syntax
Markdown is parsed and serialized according to CommonMark.
Other plugins can add support for syntax extensions.
## Syntax tree
The syntax tree used in remark is [mdast][github-mdast].
## Types
This package is fully typed with [TypeScript][].
There are no extra exported types.
It also registers `Settings` with `unified`.
If you’re passing options with `.data('settings', …)`,
make sure to import this package somewhere in your types,
as that registers the fields.
```js
/**
* @import {} from 'remark'
*/
import {unified} from 'unified'
// @ts-expect-error: `thisDoesNotExist` is not a valid option.
unified().data('settings', {thisDoesNotExist: false})
```
## Compatibility
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`remark@15`,
compatible with Node.js 16.
## Security
See [*§ Security* in `remarkjs/remark`][github-remark-security].
## Contribute
See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][]!
<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://vercel.com">Vercel</a><br><br>
<a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://motif.land">Motif</a><br><br>
<a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.hashicorp.com">HashiCorp</a><br><br>
<a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gitbook.com">GitBook</a><br><br>
<a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
<a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.netlify.com">Netlify</a><br><br>
<!--OC has a sharper image-->
<a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
<a href="https://www.coinbase.com">Coinbase</a><br><br>
<a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://themeisle.com">ThemeIsle</a><br><br>
<a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://expo.io">Expo</a><br><br>
<a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://boostnote.io">Boost Note</a><br><br>
<a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://markdown.space">Markdown Space</a><br><br>
<a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://www.holloway.com">Holloway</a><br><br>
<a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
<br>
<a href="https://opencollective.com/unified"><strong>You?</strong></a>
<br><br>
</td>
</tr>
</table>
## License
[MIT][file-license] © [Titus Wormer][author]
<!-- Definitions -->
[api-remark]: #remark-1
[author]: https://wooorm.com
[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
[badge-build-url]: https://github.com/remarkjs/remark/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
[badge-downloads-image]: https://img.shields.io/npm/dm/remark.svg
[badge-downloads-url]: https://www.npmjs.com/package/remark
[badge-size-image]: https://img.shields.io/bundlejs/size/remark
[badge-size-url]: https://bundlejs.com/?q=remark
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[file-license]: license
[github-mdast]: https://github.com/syntax-tree/mdast
[github-remark]: https://github.com/remarkjs/remark
[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
[github-remark-security]: https://github.com/remarkjs/remark#security
[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
[github-unified]: https://github.com/unifiedjs/unified
[health]: https://github.com/remarkjs/.github
[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
[npm-install]: https://docs.npmjs.com/cli/install
[opencollective]: https://opencollective.com/unified
[typescript]: https://www.typescriptlang.org
================================================
FILE: packages/remark/tsconfig.json
================================================
{
"extends": "../../tsconfig.json",
"references": [{"path": "../remark-parse/"}, {"path": "../remark-stringify/"}]
}
================================================
FILE: packages/remark-cli/.npmrc
================================================
ignore-scripts=true
package-lock=false
================================================
FILE: packages/remark-cli/cli.js
================================================
#!/usr/bin/env node
/**
* @typedef Pack
* @property {string} name
* @property {string} version
* @property {string} description
*/
import fs from 'node:fs/promises'
import {resolve} from 'import-meta-resolve'
import markdownExtensions from 'markdown-extensions'
import {remark} from 'remark'
import {args} from 'unified-args'
/** @type {Pack} */
const process_ = JSON.parse(
String(
await fs.readFile(
new URL('package.json', resolve('remark', import.meta.url))
)
)
)
/** @type {Pack} */
const cli = JSON.parse(
String(await fs.readFile(new URL('package.json', import.meta.url)))
)
args({
description: cli.description,
extensions: markdownExtensions,
ignoreName: '.' + process_.name + 'ignore',
name: process_.name,
packageField: process_.name + 'Config',
pluginPrefix: process_.name,
processor: remark,
rcName: '.' + process_.name + 'rc',
version: [
process_.name + ': ' + process_.version,
cli.name + ': ' + cli.version
].join(', ')
})
================================================
FILE: packages/remark-cli/license
================================================
(The MIT License)
Copyright (c) Titus Wormer <tituswormer@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
================================================
FILE: packages/remark-cli/package.json
================================================
{
"author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
"bin": {
"remark": "cli.js"
},
"bugs": "https://github.com/remarkjs/remark/issues",
"contributors": [
"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
],
"dependencies": {
"import-meta-resolve": "^4.0.0",
"markdown-extensions": "^2.0.0",
"remark": "^15.0.0",
"unified-args": "^11.0.0"
},
"description": "CLI to process markdown with remark",
"exports": [],
"files": [
"cli.js"
],
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
},
"homepage": "https://remark.js.org",
"keywords": [
"bin",
"cli",
"markdown",
"mdast",
"remark",
"unified"
],
"license": "MIT",
"name": "remark-cli",
"repository": "https://github.com/remarkjs/remark/tree/main/packages/remark-cli",
"scripts": {},
"typeCoverage": {
"atLeast": 100,
"strict": true
},
"type": "module",
"version": "12.0.1",
"xo": {
"prettier": true
}
}
================================================
FILE: packages/remark-cli/readme.md
================================================
# remark-cli
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
Command line interface to inspect and change markdown files with
**[remark][github-remark]**.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [CLI](#cli)
* [Examples](#examples)
* [Example: checking and formatting markdown on the CLI](#example-checking-and-formatting-markdown-on-the-cli)
* [Example: config files (JSON, YAML, JS)](#example-config-files-json-yaml-js)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
This package is a command line interface (CLI) that you can use in your terminal
or in npm scripts and the like to inspect and change markdown files.
This CLI is built around remark,
which is an ecosystem of plugins that work with markdown as structured data,
specifically ASTs (abstract syntax trees).
You can choose from the 150+ existing plugins or make your own.
See [the monorepo readme][github-remark] for info on what the remark ecosystem
is.
## When should I use this?
You can use this package when you want to work with the markdown files in your
project from the command line.
`remark-cli` has many options and you can combine it with many plugins,
so it should be possible to do what you want.
If not,
you can always use [`remark`][github-remark-core] itself manually in a script.
## Install
This package is [ESM only][esm].
In Node.js (version 16+),
install with [npm][npm-install]:
```sh
npm install remark-cli
```
## Use
Add a table of contents with [`remark-toc`][github-remark-toc] to
`readme.md`:
```sh
remark --output --use remark-toc readme.md
```
Lint all markdown files in the current directory according to the markdown style
guide with
[`remark-preset-lint-markdown-style-guide`][github-markdown-style-guide].
```sh
remark --use remark-preset-lint-markdown-style-guide .
```
## CLI
The interface of `remark-cli` is explained as follows on its help page
(`remark --help`):
```text
Usage: remark [options] [path | glob ...]
CLI to process markdown with remark
Options:
--[no-]color specify color in report (on by default)
--[no-]config search for configuration files (on by default)
-e --ext <extensions> specify extensions
--file-path <path> specify path to process as
-f --frail exit with 1 on warnings
-h --help output usage information
--[no-]ignore search for ignore files (on by default)
-i --ignore-path <path> specify ignore file
--ignore-path-resolve-from cwd|dir resolve patterns in `ignore-path` from its directory or cwd
--ignore-pattern <globs> specify ignore patterns
--inspect output formatted syntax tree
-o --output [path] specify output location
-q --quiet output only warnings and errors
-r --rc-path <path> specify configuration file
--report <reporter> specify reporter
-s --setting <settings> specify settings
-S --silent output only errors
--silently-ignore do not fail when given ignored files
--[no-]stdout specify writing to stdout (on by default)
-t --tree specify input and output as syntax tree
--tree-in specify input as syntax tree
--tree-out output syntax tree
-u --use <plugins> use plugins
--verbose report extra info for messages
-v --version output version number
-w --watch watch for changes and reprocess
Examples:
# Process `input.md`
$ remark input.md -o output.md
# Pipe
$ remark < input.md > output.md
# Rewrite all applicable files
$ remark . -o
```
More info on all these options is available at
[`unified-args`][github-unified-args],
which does the work.
`remark-cli` is `unified-args` preconfigured to:
* load `remark-` plugins
* search for markdown extensions
([`.md`, `.markdown`, etc][github-markdown-extensions])
* ignore paths found in
[`.remarkignore` files][github-unified-engine-ignore-file]
* load configuration from
[`.remarkrc`, `.remarkrc.js`, etc files and
`remarkConfig` in `package.json`s][github-unified-engine-config-file]
## Examples
### Example: checking and formatting markdown on the CLI
This example checks and formats markdown with `remark-cli`.
It assumes you’re in a Node.js package.
Install the CLI and plugins:
```sh
npm install --save-dev remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc
```
…then add an npm script in your `package.json`:
```js
/* … */
"scripts": {
/* … */
"format": "remark . --output",
/* … */
},
/* … */
```
> 💡 **Tip**:
> add ESLint and such in the `format` script too.
The above change adds a `format` script,
which can be run with `npm run format`.
It runs remark on all markdown files (`.`)
and rewrites them (`--output`).
Run `./node_modules/.bin/remark --help` for more info on the CLI.
Then add a `remarkConfig` to your `package.json` to configure remark:
```js
/* … */
"remarkConfig": {
"settings": {
"bullet": "*", // Use `*` for list item bullets (default)
// See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
},
"plugins": [
"remark-preset-lint-consistent", // Check that markdown is consistent.
"remark-preset-lint-recommended", // Few recommended rules.
[
// Generate a table of contents in `## Contents`
"remark-toc",
{
"heading": "contents"
}
]
]
},
/* … */
```
> 👉 **Note**:
> you must remove the comments in the above examples when copy/pasting them as
> comments are not supported in `package.json` files.
Finally,
you can run the npm script to check and format markdown files in your project:
```sh
npm run format
```
### Example: config files (JSON, YAML, JS)
In the previous example we saw that `remark-cli` was configured from within a
`package.json` file.
That’s a good place when the configuration is relatively short,
when you have a `package.json`,
and when you don’t need comments
(which are not allowed in JSON).
You can also define configuration in separate files in different languages.
With the `package.json` config as inspiration,
here’s a JavaScript version that can be placed in `.remarkrc.js`:
```js
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import remarkToc from 'remark-toc'
const remarkConfig = {
plugins: [
remarkPresetLintConsistent, // Check that markdown is consistent.
remarkPresetLintRecommended, // Few recommended rules.
// Generate a table of contents in `## Contents`
[remarkToc, {heading: 'contents'}]
],
settings: {
bullet: '*' // Use `*` for list item bullets (default)
// See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
}
}
export default remarkConfig
```
This is the same configuration in YAML,
which can be placed in `.remarkrc.yml`:
```yml
plugins:
# Check that markdown is consistent.
- remark-preset-lint-consistent
# Few recommended rules.
- remark-preset-lint-recommended
# Generate a table of contents in `## Contents`
- - remark-toc
- heading: contents
settings:
bullet: "*"
```
When `remark-cli` is about to process a markdown file it’ll search the file
system upwards for configuration files starting at the folder where that file
exists.
Take the following file structure as an illustration:
```text
folder/
├─ subfolder/
│ ├─ .remarkrc.json
│ └─ file.md
├─ .remarkrc.js
├─ package.json
└─ readme.md
```
When `folder/subfolder/file.md` is processed,
the closest config file is `folder/subfolder/.remarkrc.json`.
For `folder/readme.md`,
it’s `folder/.remarkrc.js`.
The order of precedence is as follows.
Earlier wins (so in the above file structure `folder/.remarkrc.js` wins over
`folder/package.json`):
1. `.remarkrc` (JSON)
2. `.remarkrc.cjs` (CJS)
3. `.remarkrc.json` (JSON)
4. `.remarkrc.js` (CJS or ESM, depending on `type: 'module'` in `package.json`)
5. `.remarkrc.mjs` (ESM)
6. `.remarkrc.yaml` (YAML)
7. `.remarkrc.yml` (YAML)
8. `package.json` with `remarkConfig` field
## Compatibility
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release,
we drop support for unmaintained versions of
Node.
This means we try to keep the current release line,
`remark-cli@12`,
compatible with Node.js 16.
## Security
See [*§ Security* in `remarkjs/remark`][github-remark-security].
## Contribute
See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][]!
<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://vercel.com">Vercel</a><br><br>
<a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://motif.land">Motif</a><br><br>
<a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.hashicorp.com">HashiCorp</a><br><br>
<a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gitbook.com">GitBook</a><br><br>
<a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
<a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.netlify.com">Netlify</a><br><br>
<!--OC has a sharper image-->
<a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
<a href="https://www.coinbase.com">Coinbase</a><br><br>
<a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://themeisle.com">ThemeIsle</a><br><br>
<a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://expo.io">Expo</a><br><br>
<a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://boostnote.io">Boost Note</a><br><br>
<a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://markdown.space">Markdown Space</a><br><br>
<a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://www.holloway.com">Holloway</a><br><br>
<a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
<br>
<a href="https://opencollective.com/unified"><strong>You?</strong></a>
<br><br>
</td>
</tr>
</table>
## License
[MIT][file-license] © [Titus Wormer][author]
<!-- Definitions -->
[author]: https://wooorm.com
[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
[badge-build-url]: https://github.com/remarkjs/remark/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
[badge-downloads-image]: https://img.shields.io/npm/dm/remark-cli.svg
[badge-downloads-url]: https://www.npmjs.com/package/remark-cli
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[file-license]: license
[github-markdown-extensions]: https://github.com/sindresorhus/markdown-extensions
[github-markdown-style-guide]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide
[github-remark]: https://github.com/remarkjs/remark
[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
[github-remark-security]: https://github.com/remarkjs/remark#security
[github-remark-toc]: https://github.com/remarkjs/remark-toc
[github-unified-args]: https://github.com/unifiedjs/unified-args
[github-unified-engine-config-file]: https://github.com/unifiedjs/unified-engine#config-files
[github-unified-engine-ignore-file]: https://github.com/unifiedjs/unified-engine#ignore-files
[health]: https://github.com/remarkjs/.github
[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
[npm-install]: https://docs.npmjs.com/cli/install
[opencollective]: https://opencollective.com/unified
================================================
FILE: packages/remark-cli/tsconfig.json
================================================
{
"extends": "../../tsconfig.json",
"references": [{"path": "../remark/"}]
}
================================================
FILE: packages/remark-parse/.npmrc
================================================
ignore-scripts=true
package-lock=false
================================================
FILE: packages/remark-parse/index.d.ts
================================================
import type {Root} from 'mdast'
import type {Extension as FromMarkdownExtension} from 'mdast-util-from-markdown'
import type {Extension as MicromarkExtension} from 'micromark-util-types'
import type {Plugin} from 'unified'
import type {Options} from './lib/index.js'
export type {Options} from './lib/index.js'
// Note: we have to use manual types here,
// instead of getting them from `lib/index.js`,
// because TS generates wrong types for functions that use `this`.
// TS makes them into classes which is incorrect.
/**
* Add support for parsing from markdown.
*
* @this
* Unified processor.
* @param
* Configuration (optional).
* @returns
* Nothing.
*/
declare const remarkParse: Plugin<
[(Readonly<Options> | null | undefined)?],
string,
Root
>
export default remarkParse
// Add custom settings supported when `remark-parse` is added.
declare module 'unified' {
interface Settings extends Options {}
interface Data {
/**
* List of `micromark` extensions to use.
*
* This type is registered by `remark-parse`.
* Values can be registered by remark plugins that extend `micromark` and
* `mdast-util-from-markdown`.
* See {@linkcode MicromarkExtension | Extension} from
* {@linkcode https://github.com/micromark/micromark/tree/main/packages/micromark-util-types | micromark-util-types}.
*/
micromarkExtensions?: Array<MicromarkExtension>
/**
* List of `mdast-util-from-markdown` extensions to use.
*
* This type is registered by `remark-parse`.
* Values can be registered by remark plugins that extend `micromark` and
* `mdast-util-from-markdown`.
* See {@linkcode FromMarkdownExtension | Extension} from
* {@linkcode https://github.com/syntax-tree/mdast-util-from-markdown#extension | mdast-util-from-markdown}.
*/
fromMarkdownExtensions?: Array<
Array<FromMarkdownExtension> | FromMarkdownExtension
>
}
}
================================================
FILE: packages/remark-parse/index.js
================================================
// Note: types exposed from `index.d.ts`.
export {default} from './lib/index.js'
================================================
FILE: packages/remark-parse/lib/index.js
================================================
/**
* @import {Root} from 'mdast'
* @import {Options as FromMarkdownOptions} from 'mdast-util-from-markdown'
* @import {Processor} from 'unified'
*/
/**
* @typedef {Omit<FromMarkdownOptions, 'extensions' | 'mdastExtensions'>} Options
*/
import {fromMarkdown} from 'mdast-util-from-markdown'
/**
* Aadd support for parsing from markdown.
*
* @this {Processor<Root>}
* Processor instance.
* @param {Readonly<Options> | null | undefined} [options]
* Configuration (optional).
* @returns {undefined}
* Nothing.
*/
export default function remarkParse(options) {
const self = this
/**
* @param {string} document
* @returns {Root}
*/
self.parser = function (document) {
return fromMarkdown(document, {
...self.data('settings'),
...options,
// Note: these options are not in the readme.
// The goal is for them to be set by plugins on `data` instead of being
// passed by users.
extensions: self.data('micromarkExtensions') || [],
mdastExtensions: self.data('fromMarkdownExtensions') || []
})
}
}
================================================
FILE: packages/remark-parse/license
================================================
(The MIT License)
Copyright (c) Titus Wormer <tituswormer@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
================================================
FILE: packages/remark-parse/package.json
================================================
{
"author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
"bugs": "https://github.com/remarkjs/remark/issues",
"contributors": [
"Elijah Hamovitz <elijahhamovitz@gmail.com>",
"Eugene Sharygin <eush77@gmail.com>",
"Ika <ikatyang@gmail.com>",
"Junyoung Choi <fluke8259@gmail.com>",
"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
],
"dependencies": {
"@types/mdast": "^4.0.0",
"mdast-util-from-markdown": "^2.0.0",
"micromark-util-types": "^2.0.0",
"unified": "^11.0.0"
},
"description": "remark plugin to add support for parsing markdown input",
"exports": "./index.js",
"files": [
"index.d.ts",
"index.js",
"lib/"
],
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
},
"homepage": "https://remark.js.org",
"keywords": [
"abstract",
"ast",
"markdown",
"mdast",
"parse",
"plugin",
"remark",
"remark-plugin",
"syntax",
"tree",
"unified"
],
"license": "MIT",
"name": "remark-parse",
"repository": "https://github.com/remarkjs/remark/tree/main/packages/remark-parse",
"scripts": {},
"sideEffects": false,
"typeCoverage": {
"atLeast": 100,
"strict": true
},
"type": "module",
"version": "11.0.0",
"xo": {
"overrides": [
{
"files": [
"**/*.d.ts"
],
"rules": {
"@typescript-eslint/array-type": [
"error",
{
"default": "generic"
}
],
"@typescript-eslint/ban-types": [
"error",
{
"extendDefaults": true
}
],
"@typescript-eslint/consistent-type-definitions": [
"error",
"interface"
]
}
}
],
"prettier": true,
"rules": {
"unicorn/no-this-assignment": "off"
}
}
}
================================================
FILE: packages/remark-parse/readme.md
================================================
# remark-parse
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
**[remark][github-remark]** plugin to add support for parsing from markdown.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`unified().use(remarkParse)`](#unifieduseremarkparse)
* [Examples](#examples)
* [Example: support GFM and frontmatter](#example-support-gfm-and-frontmatter)
* [Example: turning markdown into a man page](#example-turning-markdown-into-a-man-page)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
This package is a [unified][github-unified] ([remark][github-remark])
plugin that defines how to take markdown as input and turn it into a syntax
tree.
See [the monorepo readme][github-remark] for info on what the remark ecosystem
is.
## When should I use this?
This plugin adds support to unified for parsing markdown.
If you also need to serialize markdown,
you can alternatively use [`remark`][github-remark-core],
which combines `unified`,
this plugin,
and [`remark-stringify`][github-remark-stringify].
If you *just* want to turn markdown into HTML (with maybe a few extensions),
we recommend [`micromark`][github-micromark] instead.
If you don’t use plugins and want to access the syntax tree,
you can directly use
[`mdast-util-from-markdown`][github-mdast-util-from-markdown].
remark focusses on making it easier to transform content by abstracting these
internals away.
You can combine this plugin with other plugins to add syntax extensions.
Notable examples that deeply integrate with it are
[`remark-gfm`][github-remark-gfm],
[`remark-mdx`][github-remark-mdx],
[`remark-frontmatter`][github-remark-frontmatter],
[`remark-math`][github-remark-math],
and
[`remark-directive`][github-remark-directive].
You can also use any other [remark plugin][github-remark-plugins]
after `remark-parse`.
## Install
This package is [ESM only][esm].
In Node.js (version 16+),
install with [npm][npm-install]:
```sh
npm install remark-parse
```
In Deno with [`esm.sh`][esmsh]:
```js
import remarkParse from 'https://esm.sh/remark-parse@11'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import remarkParse from 'https://esm.sh/remark-parse@11?bundle'
</script>
```
## Use
Say we have the following module `example.js`:
```js
import rehypeStringify from 'rehype-stringify'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const value = `
# Mercury
**Mercury** is the first planet from the [Sun](https://en.wikipedia.org/wiki/Sun)
and the smallest planet in the Solar System.
`
const file = await unified()
.use(remarkParse)
.use(remarkGfm)
.use(remarkRehype)
.use(rehypeStringify)
.process(value)
console.log(String(file))
```
…then running `node example.js` yields:
```html
<h1>Mercury</h1>
<p><strong>Mercury</strong> is the first planet from the <a href="https://en.wikipedia.org/wiki/Sun">Sun</a>
and the smallest planet in the Solar System.</p>
```
## API
This package exports no identifiers.
The default export is [`remarkParse`][api-remark-parse].
### `unified().use(remarkParse)`
Add support for parsing from markdown.
###### Parameters
There are no parameters.
###### Returns
Nothing (`undefined`).
## Examples
### Example: support GFM and frontmatter
We support CommonMark by default.
Non-standard markdown extensions can be enabled with plugins.
This example shows how to support GFM features
(autolink literals, footnotes, strikethrough, tables, tasklists)
and frontmatter (YAML):
```js
import rehypeStringify from 'rehype-stringify'
import remarkFrontmatter from 'remark-frontmatter'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const doc = `---
layout: solar-system
---
# Hi ~~Mars~~Venus!
`
const file = await unified()
.use(remarkParse)
.use(remarkFrontmatter)
.use(remarkGfm)
.use(remarkRehype)
.use(rehypeStringify)
.process(doc)
console.log(String(file))
```
Yields:
```html
<h1>Hi <del>Mars</del>Venus!</h1>
```
### Example: turning markdown into a man page
Man pages (short for manual pages) are a way to document CLIs.
For an example,
type `man git-log` in your terminal.
They use an old markup format called roff.
There’s a remark plugin,
[`remark-man`][github-remark-man],
that can serialize as roff.
This example shows how to turn markdown into man pages by using unified with
`remark-parse` and `remark-man`:
```js
import remarkMan from 'remark-man'
import remarkParse from 'remark-parse'
import {unified} from 'unified'
const doc = `
# titan(7) -- largest moon of saturn
Titan is the largest moon…
`
const file = await unified().use(remarkParse).use(remarkMan).process(doc)
console.log(String(file))
```
Yields:
```roff
.TH "TITAN" "7" "January 2025" "" ""
.SH "NAME"
\fBtitan\fR - largest moon of saturn
.P
Titan is the largest moon…
```
## Syntax
Markdown is parsed according to CommonMark.
Other plugins can add support for syntax extensions.
If you’re interested in extending markdown,
see [*§ Extensions* in `micromark/micromark`][github-micromark-extensions].
## Syntax tree
The syntax tree used in remark is [mdast][github-mdast].
## Types
This package is fully typed with [TypeScript][].
It exports the additional type `Options` (which is currently empty).
## Compatibility
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`remark-parse@11`,
compatible with Node.js 16.
## Security
See [*§ Security* in `remarkjs/remark`][github-remark-security].
## Contribute
See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][]!
<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://vercel.com">Vercel</a><br><br>
<a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://motif.land">Motif</a><br><br>
<a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.hashicorp.com">HashiCorp</a><br><br>
<a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gitbook.com">GitBook</a><br><br>
<a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
<a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.netlify.com">Netlify</a><br><br>
<!--OC has a sharper image-->
<a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
<a href="https://www.coinbase.com">Coinbase</a><br><br>
<a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://themeisle.com">ThemeIsle</a><br><br>
<a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://expo.io">Expo</a><br><br>
<a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://boostnote.io">Boost Note</a><br><br>
<a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://markdown.space">Markdown Space</a><br><br>
<a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://www.holloway.com">Holloway</a><br><br>
<a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
<br>
<a href="https://opencollective.com/unified"><strong>You?</strong></a>
<br><br>
</td>
</tr>
</table>
## License
[MIT][file-license] © [Titus Wormer][author]
<!-- Definitions -->
[api-remark-parse]: #unifieduseremarkparse
[author]: https://wooorm.com
[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
[badge-build-url]: https://github.com/remarkjs/remark/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
[badge-downloads-image]: https://img.shields.io/npm/dm/remark-parse.svg
[badge-downloads-url]: https://www.npmjs.com/package/remark-parse
[badge-size-image]: https://img.shields.io/bundlejs/size/remark-parse
[badge-size-url]: https://bundlejs.com/?q=remark-parse
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[file-license]: license
[github-mdast]: https://github.com/syntax-tree/mdast
[github-mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
[github-micromark]: https://github.com/micromark/micromark
[github-micromark-extensions]: https://github.com/micromark/micromark#extensions
[github-remark]: https://github.com/remarkjs/remark
[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
[github-remark-directive]: https://github.com/remarkjs/remark-directive
[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
[github-remark-man]: https://github.com/remarkjs/remark-man
[github-remark-math]: https://github.com/remarkjs/remark-math
[github-remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx
[github-remark-plugins]: https://github.com/remarkjs/remark#plugins
[github-remark-security]: https://github.com/remarkjs/remark#security
[github-remark-stringify]: https://github.com/remarkjs/remark/tree/main/packages/remark-stringify
[github-unified]: https://github.com/unifiedjs/unified
[health]: https://github.com/remarkjs/.github
[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
[npm-install]: https://docs.npmjs.com/cli/install
[opencollective]: https://opencollective.com/unified
[typescript]: https://www.typescriptlang.org
================================================
FILE: packages/remark-parse/tsconfig.json
================================================
{
"extends": "../../tsconfig.json"
}
================================================
FILE: packages/remark-stringify/.npmrc
================================================
ignore-scripts=true
package-lock=false
================================================
FILE: packages/remark-stringify/index.d.ts
================================================
import type {Root} from 'mdast'
import type {Options as ToMarkdownExtension} from 'mdast-util-to-markdown'
import type {Plugin} from 'unified'
import type {Options} from './lib/index.js'
export type {Options} from './lib/index.js'
// Note: we have to use manual types here,
// instead of getting them from `lib/index.js`,
// because TS generates wrong types for functions that use `this`.
// TS makes them into classes which is incorrect.
/**
* Add support for serializing to markdown.
*
* @this
* Unified processor.
* @param
* Configuration (optional).
* @returns
* Nothing.
*/
declare const remarkStringify: Plugin<
[(Readonly<Options> | null | undefined)?],
Root,
string
>
export default remarkStringify
// Add custom settings supported when `remark-stringify` is added.
declare module 'unified' {
interface Settings extends Options {}
interface Data {
/**
* List of `mdast-util-to-markdown` extensions to use.
*
* This type is registered by `remark-stringify`.
* Values can be registered by remark plugins that extend
* `mdast-util-to-markdown`.
* See {@linkcode ToMarkdownExtension | Options} from
* {@linkcode https://github.com/syntax-tree/mdast-util-to-markdown#options | mdast-util-to-markdown}.
*/
toMarkdownExtensions?: Array<ToMarkdownExtension>
}
}
================================================
FILE: packages/remark-stringify/index.js
================================================
// Note: types exposed from `index.d.ts`.
export {default} from './lib/index.js'
================================================
FILE: packages/remark-stringify/lib/index.js
================================================
/**
* @import {Root} from 'mdast'
* @import {Options as ToMarkdownOptions} from 'mdast-util-to-markdown'
* @import {Processor} from 'unified'
*/
/**
* @typedef {Omit<ToMarkdownOptions, 'extensions'>} Options
*/
import {toMarkdown} from 'mdast-util-to-markdown'
/**
* Add support for serializing to markdown.
*
* @this {Processor<undefined, undefined, undefined, Root, string>}
* Processor instance.
* @param {Readonly<Options> | null | undefined} [options]
* Configuration (optional).
* @returns {undefined}
* Nothing.
*/
export default function remarkStringify(options) {
const self = this
/**
* @param {Root} tree
* @returns {string}
*/
self.compiler = function (tree) {
return toMarkdown(tree, {
...self.data('settings'),
...options,
// Note: this option is not in the readme.
// The goal is for it to be set by plugins on `data` instead of being
// passed by users.
extensions: self.data('toMarkdownExtensions') || []
})
}
}
================================================
FILE: packages/remark-stringify/license
================================================
(The MIT License)
Copyright (c) Titus Wormer <tituswormer@gmail.com>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
================================================
FILE: packages/remark-stringify/package.json
================================================
{
"author": "Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)",
"bugs": "https://github.com/remarkjs/remark/issues",
"contributors": [
"Eugene Sharygin <eush77@gmail.com>",
"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)"
],
"dependencies": {
"@types/mdast": "^4.0.0",
"mdast-util-to-markdown": "^2.0.0",
"unified": "^11.0.0"
},
"description": "remark plugin to add support for serializing markdown",
"exports": "./index.js",
"files": [
"index.d.ts",
"index.js",
"lib/"
],
"funding": {
"type": "opencollective",
"url": "https://opencollective.com/unified"
},
"homepage": "https://remark.js.org",
"keywords": [
"abstract",
"ast",
"compile",
"markdown",
"markdown",
"mdast",
"plugin",
"remark",
"remark-plugin",
"serialize",
"stringify",
"syntax",
"tree",
"unified"
],
"license": "MIT",
"name": "remark-stringify",
"repository": "https://github.com/remarkjs/remark/tree/main/packages/remark-stringify",
"scripts": {},
"sideEffects": false,
"typeCoverage": {
"atLeast": 100,
"strict": true
},
"type": "module",
"version": "11.0.0",
"xo": {
"overrides": [
{
"files": [
"**/*.d.ts"
],
"rules": {
"@typescript-eslint/array-type": [
"error",
{
"default": "generic"
}
],
"@typescript-eslint/ban-types": [
"error",
{
"extendDefaults": true
}
],
"@typescript-eslint/consistent-type-definitions": [
"error",
"interface"
]
}
}
],
"prettier": true,
"rules": {
"unicorn/no-this-assignment": "off"
}
}
}
================================================
FILE: packages/remark-stringify/readme.md
================================================
# remark-stringify
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
**[remark][github-remark]** plugin to add support for serializing to markdown.
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`unified().use(remarkStringify[, options])`](#unifieduseremarkstringify-options)
* [`Options`](#options)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
This package is a [unified][github-unified] ([remark][github-remark]) plugin
that defines how to take a syntax tree as input and turn it into serialized
markdown.
When it’s used,
markdown is serialized as the final result.
See [the monorepo readme][github-remark] for info on what the remark ecosystem
is.
## When should I use this?
This plugin adds support to unified for serializing markdown.
If you also need to parse markdown,
you can alternatively use [`remark`][github-remark-core],
which combines `unified`,
[`remark-parse`][github-remark-parse],
and this plugin.
If you don’t use plugins and have access to a syntax tree,
you can directly use [`mdast-util-to-markdown`][github-mdast-util-to-markdown],
which is used inside this plugin.
remark focusses on making it easier to transform content by abstracting these
internals away.
You can combine this plugin with other plugins to add syntax extensions.
Notable examples that deeply integrate with it are
[`remark-gfm`][github-remark-gfm],
[`remark-mdx`][github-remark-mdx],
[`remark-frontmatter`][github-remark-frontmatter],
[`remark-math`][github-remark-math],
and [`remark-directive`][github-remark-directive].
You can also use any other [remark plugin][github-remark-plugins]
before `remark-stringify`.
## Install
This package is [ESM only][esm].
In Node.js (version 16+),
install with [npm][npm-install]:
```sh
npm install remark-stringify
```
In Deno with [`esm.sh`][esmsh]:
```js
import remarkStringify from 'https://esm.sh/remark-stringify@11'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import remarkStringify from 'https://esm.sh/remark-stringify@11?bundle'
</script>
```
## Use
Say we have the following module `example.js`:
```js
import rehypeParse from 'rehype-parse'
import rehypeRemark from 'rehype-remark'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
const value = `
<h1>Uranus</h1>
<p><b>Uranus</b> is the seventh
<a href="/wiki/Planet" title="Planet">planet</a> from the Sun and is a gaseous
cyan <a href="/wiki/Ice_giant" title="Ice giant">ice giant</a>.</p>
`
const file = await unified()
.use(rehypeParse)
.use(rehypeRemark)
.use(remarkStringify)
.process(value)
console.log(String(file))
```
…then running `node example.js` yields:
```markdown
# Uranus
**Uranus** is the seventh [planet](/wiki/Planet "Planet") from the Sun and is a gaseous cyan [ice giant](/wiki/Ice_giant "Ice giant").
```
## API
This package exports no identifiers.
The default export is [`remarkStringify`][api-remark-stringify].
### `unified().use(remarkStringify[, options])`
Add support for serializing to markdown.
###### Parameters
* `options`
([`Options`][api-options], optional)
— configuration
###### Returns
Nothing (`undefined`).
### `Options`
Configuration (TypeScript type).
###### Fields
* `bullet` (`'*'`, `'+'`, or `'-'`, default: `'*'`)
— marker to use for bullets of items in unordered lists
* `bulletOther` (`'*'`, `'+'`, or `'-'`, default: `'-'` when `bullet` is
`'*'`, `'*'` otherwise)
— marker to use in certain cases where the primary bullet doesn’t work;
cannot be equal to `bullet`
* `bulletOrdered` (`'.'` or `')'`, default: `'.'`)
— marker to use for bullets of items in ordered lists
* `closeAtx` (`boolean`, default: `false`)
— add the same number of number signs (`#`) at the end of an ATX heading as
the opening sequence
* `emphasis` (`'*'` or `'_'`, default: `'*'`)
— marker to use for emphasis
* `fence` (``'`'`` or `'~'`, default: ``'`'``)
— marker to use for fenced code
* `fences` (`boolean`, default: `true`)
— use fenced code always;
when `false`,
uses fenced code if there is a language defined,
if the code is empty,
or if it starts or ends in blank lines
* `handlers` (`Handlers`, optional)
— handle particular nodes;
see [`mdast-util-to-markdown`][github-mdast-util-to-markdown] for more info
* `incrementListMarker` (`boolean`, default: `true`)
— increment the counter of ordered lists items
* `join` (`Array<Join>`, optional)
— how to join blocks;
see [`mdast-util-to-markdown`][github-mdast-util-to-markdown] for more info
* `listItemIndent` (`'mixed'`, `'one'`, or `'tab'`, default: `'one'`)
— how to indent the content of list items;
either with the size of the bullet plus one space (when `'one'`),
a tab stop (`'tab'`),
or depending on the item and its parent list: `'mixed'` uses `'one'` if the
item and list are tight and `'tab'` otherwise
* `quote` (`'"'` or `"'"`, default: `'"'`)
— marker to use for titles
* `resourceLink` (`boolean`, default: `false`)
— always use resource links (`[text](url)`);
when `false`, uses autolinks (`<https://example.com>`) when possible
* `rule` (`'*'`, `'-'`, or `'_'`, default: `'*'`)
— marker to use for thematic breaks
* `ruleRepetition` (`number`, default: `3`, min: `3`)
— number of markers to use for thematic breaks
* `ruleSpaces` (`boolean`, default: `false`)
— add spaces between markers in thematic breaks
* `setext` (`boolean`, default: `false`)
— use setext headings when possible;
when `true`, uses setext headings (`heading\n=======`) for non-empty rank 1
or 2 headings
* `strong` (`'*'` or `'_'`, default: `'*'`)
— marker to use for strong
* `tightDefinitions` (`boolean`, default: `false`)
— join definitions without a blank line
* `unsafe` (`Array<Unsafe>`, optional)
— schemas that define when characters cannot occur;
see [`mdast-util-to-markdown`][github-mdast-util-to-markdown] for more info
<!-- Note: `extensions` intentionally not supported/documented. -->
## Syntax
Markdown is serialized according to CommonMark but care is taken to format in a
way that works with most markdown parsers.
Other plugins can add support for syntax extensions.
## Syntax tree
The syntax tree used in remark is [mdast][github-mdast].
## Types
This package is fully typed with [TypeScript][].
It exports the additional type [`Options`][api-options].
It also registers `Settings` with `unified`.
If you’re passing options with `.data('settings', …)`,
make sure to import this package somewhere in your types,
as that registers the fields.
```js
/**
* @import {} from 'remark-stringify'
*/
import {unified} from 'unified'
// @ts-expect-error: `thisDoesNotExist` is not a valid option.
unified().data('settings', {thisDoesNotExist: false})
```
## Compatibility
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line,
`remark-stringify@11`,
compatible with Node.js 16.
## Security
See [*§ Security* in `remarkjs/remark`][github-remark-security].
## Contribute
See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][]!
<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://vercel.com">Vercel</a><br><br>
<a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://motif.land">Motif</a><br><br>
<a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.hashicorp.com">HashiCorp</a><br><br>
<a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gitbook.com">GitBook</a><br><br>
<a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
<a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.netlify.com">Netlify</a><br><br>
<!--OC has a sharper image-->
<a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
<a href="https://www.coinbase.com">Coinbase</a><br><br>
<a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://themeisle.com">ThemeIsle</a><br><br>
<a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://expo.io">Expo</a><br><br>
<a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://boostnote.io">Boost Note</a><br><br>
<a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://markdown.space">Markdown Space</a><br><br>
<a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://www.holloway.com">Holloway</a><br><br>
<a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
<br>
<a href="https://opencollective.com/unified"><strong>You?</strong></a>
<br><br>
</td>
</tr>
</table>
## License
[MIT][file-license] © [Titus Wormer][author]
<!-- Definitions -->
[api-options]: #options
[api-remark-stringify]: #unifieduseremarkstringify-options
[author]: https://wooorm.com
[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
[badge-build-url]: https://github.com/remarkjs/remark/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
[badge-downloads-image]: https://img.shields.io/npm/dm/remark-stringify.svg
[badge-downloads-url]: https://www.npmjs.com/package/remark-stringify
[badge-size-image]: https://img.shields.io/bundlejs/size/remark-stringify
[badge-size-url]: https://bundlejs.com/?q=remark-stringify
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[file-license]: license
[github-mdast]: https://github.com/syntax-tree/mdast
[github-mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
[github-remark]: https://github.com/remarkjs/remark
[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
[github-remark-directive]: https://github.com/remarkjs/remark-directive
[github-remark-frontmatter]: https://github.com/remarkjs/remark-frontmatter
[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
[github-remark-math]: https://github.com/remarkjs/remark-math
[github-remark-mdx]: https://github.com/mdx-js/mdx/tree/main/packages/remark-mdx
[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
[github-remark-plugins]: https://github.com/remarkjs/remark#plugins
[github-remark-security]: https://github.com/remarkjs/remark#security
[github-unified]: https://github.com/unifiedjs/unified
[health]: https://github.com/remarkjs/.github
[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
[npm-install]: https://docs.npmjs.com/cli/install
[opencollective]: https://opencollective.com/unified
[typescript]: https://www.typescriptlang.org
================================================
FILE: packages/remark-stringify/tsconfig.json
================================================
{
"extends": "../../tsconfig.json"
}
================================================
FILE: readme.md
================================================
# ![remark][file-logo]
[![Build][badge-build-image]][badge-build-url]
[![Coverage][badge-coverage-image]][badge-coverage-url]
[![Downloads][badge-downloads-image]][badge-downloads-url]
[![Size][badge-size-image]][badge-size-url]
**remark** is a tool that transforms markdown with plugins.
These plugins can inspect and change your markup.
You can use remark on the server,
the client,
CLIs,
deno,
etc.
## Feature highlights
* [x] **[compliant][section-syntax]**
— 100% to CommonMark,
100% to GFM or MDX with a plugin
* [x] **[ASTs][section-syntax-tree]**
— inspecting and changing content made easy
* [x] **[popular][]**
— world’s most popular markdown parser
* [x] **[plugins][section-plugins]**
— 150+ plugins you can pick and choose from
## Intro
remark is an ecosystem of plugins that work with markdown as structured data,
specifically ASTs (abstract syntax trees).
ASTs make it easy for programs to deal with markdown.
We call those programs plugins.
Plugins inspect and change trees.
You can use the many existing plugins or you can make your own.
* to learn markdown,
see this [cheatsheet and tutorial][commonmark-help]
* for more about us,
see [`unifiedjs.com`][unifiedjs]
* for questions,
see [support][health-support]
* to help,
see [contribute][section-contribute] or [sponsor][section-sponsor] below
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Plugins](#plugins)
* [Examples](#examples)
* [Example: turning markdown into HTML](#example-turning-markdown-into-html)
* [Example: support for GFM and frontmatter](#example-support-for-gfm-and-frontmatter)
* [Example: checking markdown](#example-checking-markdown)
* [Example: checking and formatting markdown on the CLI](#example-checking-and-formatting-markdown-on-the-cli)
* [Syntax](#syntax)
* [Syntax tree](#syntax-tree)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Contribute](#contribute)
* [Sponsor](#sponsor)
* [License](#license)
## What is this?
With this project and a plugin,
you can turn this markdown:
```markdown
# Hello, *Mercury*!
```
…into the following HTML:
```html
<h1>Hello, <em>Mercury</em>!</h1>
```
<details><summary>Show example code</summary>
```js
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeStringify)
.process('# Hello, *Mercury*!')
console.log(String(file)) // => '<h1>Hello, <em>Mercury</em>!</h1>'
```
</details>
With another plugin,
you can turn this markdown:
```markdown
# Hi, Saturn!
```
…into the following markdown:
```markdown
## Hi, Saturn!
```
<details><summary>Show example code</summary>
```js
/**
* @import {Root} from 'mdast'
*/
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {visit} from 'unist-util-visit'
const file = await unified()
.use(remarkParse)
.use(myRemarkPluginToIncreaseHeadings)
.use(remarkStringify)
.process('# Hi, Saturn!')
console.log(String(file)) // => '## Hi, Saturn!'
function myRemarkPluginToIncreaseHeadings() {
/**
* @param {Root} tree
*/
return function (tree) {
visit(tree, function (node) {
if (node.type === 'heading') {
node.depth++
}
})
}
}
```
</details>
You can use remark for many different things.
**[unified][github-unified]** is the core project that transforms content with
ASTs.
**remark** adds support for markdown to unified.
**[mdast][github-mdast]** is the markdown AST that remark uses.
This GitHub repository is a monorepo that contains the following packages:
* [`remark-parse`][github-remark-parse]
— plugin to take markdown as input and turn it into a syntax tree (mdast)
* [`remark-stringify`][github-remark-stringify]
— plugin to take a syntax tree (mdast) and turn it into markdown as output
* [`remark`][github-remark-core]
— `unified`, `remark-parse`, and `remark-stringify`,
useful when input and output are markdown
* [`remark-cli`][github-remark-cli]
— CLI around `remark` to inspect and format markdown in scripts
## When should I use this?
Depending on the input you have and output you want,
you can use different parts of remark.
If the input is markdown,
you can use `remark-parse` with `unified`.
If the output is markdown,
you can use `remark-stringify` with `unified`.
If both the input and output are markdown,
you can use `remark` on its own.
When you want to inspect and format markdown files in a project,
you can use `remark-cli`.
If you *just* want to turn markdown into HTML (with maybe a few extensions),
we recommend [`micromark`][github-micromark] instead.
If you don’t use plugins and want to deal with syntax trees manually,
you can use [`mdast-util-from-markdown`][github-mdast-util-from-markdown] and
[`mdast-util-to-markdown`][github-mdast-util-to-markdown].
## Plugins
remark plugins deal with markdown.
Some popular examples are:
* [`remark-gfm`][github-remark-gfm]
— add support for GFM (GitHub flavored markdown)
* [`remark-lint`][github-remark-lint]
— inspect markdown and warn about inconsistencies
* [`remark-toc`][github-remark-toc]
— generate a table of contents
* [`remark-rehype`][github-remark-rehype]
— turn markdown into HTML
These plugins are exemplary because what they do and how they do it is quite
different,
respectively to extend markdown syntax,
inspect trees,
change trees,
and transform to other syntax trees.
You can choose from the 150+ plugins that already exist.
Here are three good ways to find plugins:
* [`awesome-remark`][github-awesome-remark]
— selection of the most awesome projects
* [List of plugins][file-list-of-plugins]
— list of all plugins
* [`remark-plugin` topic][github-topic-remark-plugin]
— any tagged repo on GitHub
Some plugins are maintained by us here in the `@remarkjs` organization while
others are maintained by folks elsewhere.
Anyone can make remark plugins,
so as always when choosing whether to include
dependencies in your project,
make sure to carefully assess the quality of remark plugins too.
## Examples
### Example: turning markdown into HTML
remark is an ecosystem around markdown.
A different ecosystem is for HTML:
[rehype][github-rehype].
The following example turns markdown into HTML by combining both ecosystems with
[`remark-rehype`][github-remark-rehype]:
```js
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const file = await unified()
.use(remarkParse)
.use(remarkRehype)
.use(rehypeSanitize)
.use(rehypeStringify)
.process('# Hello, Neptune!')
console.log(String(file))
```
Yields:
```html
<h1>Hello, Neptune!</h1>
```
### Example: support for GFM and frontmatter
remark supports CommonMark by default.
Non-standard markdown extensions can be enabled with plugins.
The following example adds support for GFM
(autolink literals, footnotes, strikethrough, tables, tasklists)
and frontmatter (YAML):
```js
import rehypeStringify from 'rehype-stringify'
import remarkFrontmatter from 'remark-frontmatter'
import remarkGfm from 'remark-gfm'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'
const value = `---
layout: solar-system
---
# Hi ~~Mars~~Venus!
`
const file = await unified()
.use(remarkParse)
.use(remarkFrontmatter)
.use(remarkGfm)
.use(remarkRehype)
.use(rehypeStringify)
.process(value)
console.log(String(file))
```
Yields:
```html
<h1>Hi <del>Mars</del>Venus!</h1>
```
### Example: checking markdown
The following example checks that markdown code style is consistent and follows
recommended best practices:
```js
import {remark} from 'remark'
import remarkPresetLintConsistent from 'remark-preset-lint-consistent'
import remarkPresetLintRecommended from 'remark-preset-lint-recommended'
import {reporter} from 'vfile-reporter'
const file = await remark()
.use(remarkPresetLintConsistent)
.use(remarkPresetLintRecommended)
.process('1) Hello, _Jupiter_ and *Neptune*!')
console.error(reporter(file))
```
Yields:
```text
1:2 warning Unexpected ordered list marker `)`, expected `.` ordered-list-marker-style remark-lint
1:25-1:34 warning Unexpected emphasis marker `*`, expected `_` emphasis-marker remark-lint
[cause]:
1:11-1:20 info Emphasis marker style `'_'` first defined for `'consistent'` here emphasis-marker remark-lint
1:35 warning Unexpected missing final newline character, expected line feed (`\n`) at end of file final-newline remark-lint
⚠ 3 warnings
```
### Example: checking and formatting markdown on the CLI
The following example checks and formats markdown with `remark-cli`,
which is the CLI (command line interface) of remark that you can use in your
terminal.
This example assumes you’re in a Node.js package.
First,
install the CLI and plugins:
```sh
npm install --save-dev remark-cli remark-preset-lint-consistent remark-preset-lint-recommended remark-toc
```
…then add an npm script in your `package.json`:
```js
/* … */
"scripts": {
/* … */
"format": "remark . --output",
/* … */
},
/* … */
```
> 💡 **Tip**:
> add ESLint and such in the `format` script too.
The above change adds a `format` script,
which can be run with `npm run format`.
It runs remark on all markdown files (`.`) and rewrites them (`--output`).
Run `./node_modules/.bin/remark --help` for more info on the CLI.
Then,
add a `remarkConfig` to your `package.json` to configure remark:
```js
/* … */
"remarkConfig": {
"settings": {
"bullet": "*", // Use `*` for list item bullets (default)
// See <https://github.com/remarkjs/remark/tree/main/packages/remark-stringify> for more options.
},
"plugins": [
"remark-preset-lint-consistent", // Check that markdown is consistent.
"remark-preset-lint-recommended", // Few recommended rules.
[
// Generate a table of contents in `## Contents`
"remark-toc",
{
"heading": "contents"
}
]
]
},
/* … */
```
> 👉 **Note**:
> you must remove the comments in the above examples when copy/pasting them as
> comments are not supported in `package.json` files.
Finally,
you can run the npm script to check and format markdown files in your project:
```sh
npm run format
```
## Syntax
Markdown is parsed and serialized according to CommonMark.
Other plugins can add support for syntax extensions.
We use [`micromark`][github-micromark] for our parsing.
See its documentation for more information on markdown,
CommonMark,
and extensions.
## Syntax tree
The syntax tree used in remark is [mdast][github-mdast].
It represents markdown constructs as JSON objects.
This markdown:
```markdown
## Hello *Pluto*!
```
…yields the following tree (positional info remove for brevity):
```js
{
type: 'heading',
depth: 2,
children: [
{type: 'text', value: 'Hello '},
{type: 'emphasis', children: [{type: 'text', value: 'Pluto'}]}
{type: 'text', value: '!'}
]
}
```
## Types
The remark organization and the unified collective as a whole is fully typed
with [TypeScript][].
Types for mdast are available in [`@types/mdast`][github-types-mdast].
For TypeScript to work,
it is important to type your plugins.
For example:
```js
/**
* @import {Root} from 'mdast'
* @import {VFile} from 'vfile'
*/
/**
* @typedef Options
* Configuration.
* @property {boolean | null | undefined} [someField]
* Some option (optional).
*/
/**
* My plugin.
*
* @param {Options | null | undefined} [options]
* Configuration (optional).
* @returns
* Transform.
*/
export function myRemarkPluginAcceptingOptions(options) {
/**
* Transform.
*
* @param {Root} tree
* Tree.
* @param {VFile} file
* File
* @returns {undefined}
* Nothing.
*/
return function (tree, file) {
// Do things.
}
}
```
## Compatibility
Projects maintained by the unified collective are compatible with maintained
versions of Node.js.
When we cut a new major release,
we drop support for unmaintained versions of Node.
This means we try to keep the current release line compatible with Node.js 16.
## Security
As markdown can be turned into HTML and improper use of HTML can open you up to
[cross-site scripting (XSS)][wikipedia-xss] attacks,
use of remark can be unsafe.
When going to HTML,
you will combine remark with **[rehype][github-rehype]**,
in which case you should use [`rehype-sanitize`][github-rehype-sanitize].
Another security aspect is DDoS attacks.
An attacker could cause a crash or slow down with big files.
Crashes can also originate from smaller payloads,
often when thousands of things (such as lists or links) are opened.
It is wise to cap the accepted size of input
(500kb can hold a big book)
and to process content in a different thread or worker so that it can be
stopped when needed.
Use of remark plugins could also open you up to other attacks.
Carefully assess each plugin and the risks involved in using them.
For info on how to submit a report,
see our [security policy][health-security].
## Contribute
See [`contributing.md`][health-contributing] in [`remarkjs/.github`][health]
for ways to get started.
See [`support.md`][health-support] for ways to get help.
This project has a [code of conduct][health-coc].
By interacting with this repository,
organization,
or community you agree to abide by its terms.
## Sponsor
Support this effort and give back by sponsoring on [OpenCollective][]!
<table>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://vercel.com">Vercel</a><br><br>
<a href="https://vercel.com"><img src="https://avatars1.githubusercontent.com/u/14985020?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://motif.land">Motif</a><br><br>
<a href="https://motif.land"><img src="https://avatars1.githubusercontent.com/u/74457950?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.hashicorp.com">HashiCorp</a><br><br>
<a href="https://www.hashicorp.com"><img src="https://avatars1.githubusercontent.com/u/761456?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gitbook.com">GitBook</a><br><br>
<a href="https://www.gitbook.com"><img src="https://avatars1.githubusercontent.com/u/7111340?s=256&v=4" width="128"></a>
</td>
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.gatsbyjs.org">Gatsby</a><br><br>
<a href="https://www.gatsbyjs.org"><img src="https://avatars1.githubusercontent.com/u/12551863?s=256&v=4" width="128"></a>
</td>
</tr>
<tr valign="middle">
</tr>
<tr valign="middle">
<td width="20%" align="center" rowspan="2" colspan="2">
<a href="https://www.netlify.com">Netlify</a><br><br>
<!--OC has a sharper image-->
<a href="https://www.netlify.com"><img src="https://images.opencollective.com/netlify/4087de2/logo/256.png" width="128"></a>
</td>
<td width="10%" align="center">
<a href="https://www.coinbase.com">Coinbase</a><br><br>
<a href="https://www.coinbase.com"><img src="https://avatars1.githubusercontent.com/u/1885080?s=256&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://themeisle.com">ThemeIsle</a><br><br>
<a href="https://themeisle.com"><img src="https://avatars1.githubusercontent.com/u/58979018?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://expo.io">Expo</a><br><br>
<a href="https://expo.io"><img src="https://avatars1.githubusercontent.com/u/12504344?s=128&v=4" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://boostnote.io">Boost Note</a><br><br>
<a href="https://boostnote.io"><img src="https://images.opencollective.com/boosthub/6318083/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://markdown.space">Markdown Space</a><br><br>
<a href="https://markdown.space"><img src="https://images.opencollective.com/markdown-space/e1038ed/logo/128.png" width="64"></a>
</td>
<td width="10%" align="center">
<a href="https://www.holloway.com">Holloway</a><br><br>
<a href="https://www.holloway.com"><img src="https://avatars1.githubusercontent.com/u/35904294?s=128&v=4" width="64"></a>
</td>
<td width="10%"></td>
<td width="10%"></td>
</tr>
<tr valign="middle">
<td width="100%" align="center" colspan="8">
<br>
<a href="https://opencollective.com/unified"><strong>You?</strong></a>
<br><br>
</td>
</tr>
</table>
## License
[MIT](license) © [Titus Wormer](https://wooorm.com)
<!-- Definitions -->
[badge-build-image]: https://github.com/remarkjs/remark/workflows/main/badge.svg
[badge-build-url]: https://github.com/remarkjs/remark/actions
[badge-coverage-image]: https://img.shields.io/codecov/c/github/remarkjs/remark.svg
[badge-coverage-url]: https://codecov.io/github/remarkjs/remark
[badge-downloads-image]: https://img.shields.io/npm/dm/remark.svg
[badge-downloads-url]: https://www.npmjs.com/package/remark
[badge-size-image]: https://img.shields.io/bundlejs/size/remark
[badge-size-url]: https://bundlejs.com/?q=remark
[commonmark-help]: https://commonmark.org/help/
[file-list-of-plugins]: doc/plugins.md#list-of-plugins
[file-logo]: https://raw.githubusercontent.com/remarkjs/remark/1f338e72/logo.svg?sanitize=true
[github-awesome-remark]: https://github.com/remarkjs/awesome-remark
[github-mdast]: https://github.com/syntax-tree/mdast
[github-mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown
[github-mdast-util-to-markdown]: https://github.com/syntax-tree/mdast-util-to-markdown
[github-micromark]: https://github.com/micromark/micromark
[github-rehype]: https://github.com/rehypejs/rehype
[github-rehype-sanitize]: https://github.com/rehypejs/rehype-sanitize
[github-remark-cli]: https://github.com/remarkjs/remark/tree/main/packages/remark-cli
[github-remark-core]: https://github.com/remarkjs/remark/tree/main/packages/remark
[github-remark-gfm]: https://github.com/remarkjs/remark-gfm
[github-remark-lint]: https://github.com/remarkjs/remark-lint
[github-remark-parse]: https://github.com/remarkjs/remark/tree/main/packages/remark-parse
[github-remark-rehype]: https://github.com/remarkjs/remark-rehype
[github-remark-stringify]: packages/remark-stringify/
[github-remark-toc]: https://github.com/remarkjs/remark-toc
[github-topic-remark-plugin]: https://github.com/topics/remark-plugin
[github-types-mdast]: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mdast
[github-unified]: https://github.com/unifiedjs/unified
[health]: https://github.com/remarkjs/.github
[health-coc]: https://github.com/remarkjs/.github/blob/main/code-of-conduct.md
[health-contributing]: https://github.com/remarkjs/.github/blob/main/contributing.md
[health-security]: https://github.com/remarkjs/.github/blob/main/security.md
[health-support]: https://github.com/remarkjs/.github/blob/main/support.md
[opencollective]: https://opencollective.com/unified
[popular]: https://www.npmtrends.com/remark-parse-vs-marked-vs-micromark-vs-markdown-it
[section-contribute]: #contribute
[section-plugins]: #plugins
[section-sponsor]: #sponsor
[section-syntax]: #syntax
[section-syntax-tree]: #syntax-tree
[typescript]: https://www.typescriptlang.org
[unifiedjs]: https://unifiedjs.com
[wikipedia-xss]: https://en.wikipedia.org/wiki/Cross-site_scripting
================================================
FILE: test.js
================================================
import assert from 'node:assert/strict'
import {exec as execCallback} from 'node:child_process'
import test from 'node:test'
import {promisify} from 'node:util'
import {fileURLToPath} from 'node:url'
import {gfmFromMarkdown, gfmToMarkdown} from 'mdast-util-gfm'
import {gfm} from 'micromark-extension-gfm'
import {remark} from 'remark'
import remarkParse from 'remark-parse'
import remarkStringify from 'remark-stringify'
import {unified} from 'unified'
import {removePosition} from 'unist-util-remove-position'
const exec = promisify(execCallback)
test('remark', async function (t) {
await t.test('should expose the public api', async function () {
assert.deepEqual(Object.keys(await import('remark')).sort(), ['remark'])
})
await t.test('should process a file', async function () {
assert.equal(remark().processSync('*foo*').toString(), '*foo*\n')
})
await t.test('should accept settings', async function () {
assert.equal(
remark()
.data('settings', {closeAtx: true})
.processSync('# foo')
.toString(),
'# foo #\n'
)
})
})
test('remark-cli', async function (t) {
const binary = fileURLToPath(
new URL('packages/remark-cli/cli.js', import.meta.url)
)
await t.test('should show help on `--help`', async function () {
const result = await exec(binary + ' --help')
assert.equal(
result.stdout,
[
'Usage: remark [options] [path | glob ...]',
'',
' CLI to process markdown with remark',
'',
'Options:',
'',
' --[no-]color specify color in report (on by default)',
' --[no-]config search for configuration files (on by default)',
' -e --ext <extensions> specify extensions',
' --file-path <path> specify path to process as',
' -f --frail exit with 1 on warnings',
' -h --help output usage information',
' --[no-]ignore search for ignore files (on by default)',
' -i --ignore-path <path> specify ignore file',
' --ignore-path-resolve-from cwd|dir resolve patterns in `ignore-path` from its directory or cwd',
' --ignore-pattern <globs> specify ignore patterns',
' --inspect output formatted syntax tree',
' -o --output [path] specify output location',
' -q --quiet output only warnings and errors',
' -r --rc-path <path> specify configuration file',
' --report <reporter> specify reporter',
' -s --setting <settings> specify settings',
' -S --silent output only errors',
' --silently-ignore do not fail when given ignored files',
' --[no-]stdout specify writing to stdout (on by default)',
' -t --tree specify input and output as syntax tree',
' --tree-in specify input as syntax tree',
' --tree-out output syntax tree',
' -u --use <plugins> use plugins',
' --verbose report extra info for messages',
' -v --version output version number',
' -w --watch watch for changes and reprocess',
'',
'Examples:',
'',
' # Process `input.md`',
' $ remark input.md -o output.md',
'',
' # Pipe',
' $ remark < input.md > output.md',
'',
' # Rewrite all applicable files',
' $ remark . -o',
''
].join('\n')
)
})
await t.test('should show version on `--version`', async function () {
const result = await exec(binary + ' --version')
assert.match(result.stdout, /remark: \d+\.\d+\.\d+/)
assert.match(result.stdout, /remark-cli: \d+\.\d+\.\d+/)
})
})
test('remark-parse', async function (t) {
await t.test('should expose the public api', async function () {
assert.deepEqual(Object.keys(await import('remark-parse')).sort(), [
'default'
])
})
await t.test('should parse', async function () {
assert.deepEqual(unified().use(remarkParse).parse('Alfred'), {
type: 'root',
children: [
{
type: 'paragraph',
children: [
{
type: 'text',
value: 'Alfred',
position: {
start: {line: 1, column: 1, offset: 0},
end: {line: 1, column: 7, offset: 6}
}
}
],
position: {
start: {line: 1, column: 1, offset: 0},
end: {line: 1, column: 7, offset: 6}
}
}
],
position: {
start: {line: 1, column: 1, offset: 0},
end: {line: 1, column: 7, offset: 6}
}
})
})
await t.test('should support extensions', function () {
const tree = unified()
.data('micromarkExtensions', [gfm()])
.data('fromMarkdownExtensions', [gfmFromMarkdown()])
.use(remarkParse)
.parse('* [x] contact@example.com ~~strikethrough~~')
removePosition(tree, {force: true})
assert.deepEqual(tree, {
type: 'root',
children: [
{
type: 'list',
ordered: false,
start: null,
spread: false,
children: [
{
type: 'listItem',
spread: false,
checked: true,
children: [
{
type: 'paragraph',
children: [
{
type: 'link',
title: null,
url: 'mailto:contact@example.com',
children: [{type: 'text', value: 'contact@example.com'}]
},
{type: 'text', value: ' '},
{
type: 'delete',
children: [{type: 'text', value: 'strikethrough'}]
}
]
}
]
}
]
}
]
})
})
})
test('remark-stringify', async function (t) {
await t.test('should expose the public api', async function () {
assert.deepEqual(Object.keys(await import('remark-stringify')).sort(), [
'default'
])
})
await t.test('should serialize', async function () {
assert.equal(
unified()
.use(remarkStringify)
.stringify({
type: 'root',
children: [
{type: 'paragraph', children: [{type: 'text', value: 'Alfred'}]}
]
}),
'Alfred\n'
)
})
await t.test('should support extensions', async function () {
const result = unified()
.data('toMarkdownExtensions', [gfmToMarkdown()])
.use(remarkStringify)
.stringify({
type: 'root',
children: [
{
type: 'heading',
depth: 1,
children: [{type: 'text', value: 'GFM'}]
},
{
type: 'heading',
depth: 2,
children: [{type: 'text', value: 'Autolink literals'}]
},
{
type: 'paragraph',
children: [
{
type: 'link',
title: null,
url: 'http://www.example.com',
children: [{type: 'text', value: 'www.example.com'}]
},
{type: 'text', value: ', '},
{
type: 'link',
title: null,
url: 'https://example.com',
children: [{type: 'text', value: 'https://example.com'}]
},
{type: 'text', value: ', and '},
{
type: 'link',
title: null,
url: 'mailto:contact@example.com',
children: [{type: 'text', value: 'contact@example.com'}]
},
{type: 'text', value: '.'}
]
},
{
type: 'heading',
depth: 2,
children: [{type: 'text', value: 'Strikethrough'}]
},
{
type: 'paragraph',
children: [
{
type: 'delete',
children: [{type: 'text', value: 'one'}]
},
{type: 'text', value: ' or '},
{
type: 'delete',
children: [{type: 'text', value: 'two'}]
},
{type: 'text', value: ' tildes.'}
]
},
{
type: 'heading',
depth: 2,
children: [{type: 'text', value: 'Table'}]
},
{
type: 'table',
align: [null, 'left', 'right', 'center'],
children: [
{
type: 'tableRow',
children: [
{type: 'tableCell', children: [{type: 'text', value: 'a'}]},
{type: 'tableCell', children: [{type: 'text', value: 'b'}]},
{type: 'tableCell', children: [{type: 'text', value: 'c'}]},
{type: 'tableCell', children: [{type: 'text', value: 'd'}]}
]
}
]
},
{
type: 'heading',
depth: 2,
children: [{type: 'text', value: 'Tasklist'}]
},
{
type: 'list',
ordered: false,
start: undefined,
spread: false,
children: [
{
type: 'listItem',
spread: false,
checked: false,
children: [
{
type: 'paragraph',
children: [{type: 'text', value: 'to do'}]
}
]
},
{
type: 'listItem',
spread: false,
checked: true,
children: [
{
type: 'paragraph',
children: [{type: 'text', value: 'done'}]
}
]
}
]
}
]
})
assert.equal(
result,
[
'# GFM',
'',
'## Autolink literals',
'',
'[www.example.com](http://www.example.com), <https://example.com>, and <contact@example.com>.',
'',
'## Strikethrough',
'',
'~~one~~ or ~~two~~ tildes.',
'',
'## Table',
'',
'| a | b | c | d |',
'| - | :- | -: | :-: |',
'',
'## Tasklist',
'',
'* [ ] to do',
'* [x] done',
''
].join('\n')
)
})
})
================================================
FILE: tsconfig.json
================================================
{
"compilerOptions": {
"checkJs": true,
"customConditions": ["development"],
"declarationMap": true,
"declaration": true,
"emitDeclarationOnly": true,
"exactOptionalPropertyTypes": true,
"lib": ["es2022"],
"module": "node16",
"strict": true,
"target": "es2022"
},
"exclude": ["**/coverage/", "**/node_modules/"],
"include": [
"**/*.js",
"packages/remark/index.d.ts",
"packages/remark-parse/index.d.ts",
"packages/remark-stringify/index.d.ts"
]
}
gitextract_pbroh9s0/ ├── .editorconfig ├── .github/ │ └── workflows/ │ ├── bb.yml │ └── main.yml ├── .gitignore ├── .mailmap ├── .npmrc ├── .prettierignore ├── changelog.md ├── doc/ │ ├── getting-started.md │ ├── plugins.md │ └── products.md ├── license ├── package.json ├── packages/ │ ├── remark/ │ │ ├── .npmrc │ │ ├── index.d.ts │ │ ├── index.js │ │ ├── license │ │ ├── package.json │ │ ├── readme.md │ │ └── tsconfig.json │ ├── remark-cli/ │ │ ├── .npmrc │ │ ├── cli.js │ │ ├── license │ │ ├── package.json │ │ ├── readme.md │ │ └── tsconfig.json │ ├── remark-parse/ │ │ ├── .npmrc │ │ ├── index.d.ts │ │ ├── index.js │ │ ├── lib/ │ │ │ └── index.js │ │ ├── license │ │ ├── package.json │ │ ├── readme.md │ │ └── tsconfig.json │ └── remark-stringify/ │ ├── .npmrc │ ├── index.d.ts │ ├── index.js │ ├── lib/ │ │ └── index.js │ ├── license │ ├── package.json │ ├── readme.md │ └── tsconfig.json ├── readme.md ├── test.js └── tsconfig.json
SYMBOL INDEX (6 symbols across 4 files)
FILE: packages/remark-parse/index.d.ts
type Settings (line 32) | interface Settings extends Options {}
type Data (line 34) | interface Data {
FILE: packages/remark-parse/lib/index.js
function remarkParse (line 23) | function remarkParse(options) {
FILE: packages/remark-stringify/index.d.ts
type Settings (line 31) | interface Settings extends Options {}
type Data (line 33) | interface Data {
FILE: packages/remark-stringify/lib/index.js
function remarkStringify (line 23) | function remarkStringify(options) {
Condensed preview — 45 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (141K chars).
[
{
"path": ".editorconfig",
"chars": 147,
"preview": "root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\nindent_size = 2\nindent_style = space\ninsert_final_newline = true\ntrim_"
},
{
"path": ".github/workflows/bb.yml",
"chars": 336,
"preview": "jobs:\n main:\n runs-on: ubuntu-latest\n steps:\n - uses: unifiedjs/beep-boop-beta@main\n with:\n "
},
{
"path": ".github/workflows/main.yml",
"chars": 1184,
"preview": "jobs:\n canary:\n name: canary / ${{matrix.package}}\n runs-on: ubuntu-latest\n steps:\n - uses: actions/check"
},
{
"path": ".gitignore",
"chars": 180,
"preview": "*.d.ts\n*.log\n*.map\n*.tsbuildinfo\n.DS_Store\ncoverage/\nnode_modules/\nyarn.lock\n!/packages/remark-parse/index.d.ts\n!/packag"
},
{
"path": ".mailmap",
"chars": 729,
"preview": "Titus Wormer <tituswormer@gmail.com>\nIsaac Z. Schlueter <i@izs.me>\nKomatsu Seiji <skomatsu.comutt@gmail.com>\nCyril Lakec"
},
{
"path": ".npmrc",
"chars": 39,
"preview": "ignore-scripts=true\npackage-lock=false\n"
},
{
"path": ".prettierignore",
"chars": 15,
"preview": "coverage/\n*.md\n"
},
{
"path": "changelog.md",
"chars": 121,
"preview": "# Changelog\n\nSee [GitHub Releases][releases] for the changelog.\n\n[releases]: https://github.com/remarkjs/remark/releases"
},
{
"path": "doc/getting-started.md",
"chars": 168,
"preview": "# Getting started\n\nSee [the monorepo readme][remark] for what the remark ecosystem is and examples\nof how to get started"
},
{
"path": "doc/plugins.md",
"chars": 25334,
"preview": "![remark][file-logo]\n\n# Plugins\n\n**remark** is a tool that transforms markdown with plugins.\nSee [the monorepo readme][g"
},
{
"path": "doc/products.md",
"chars": 121,
"preview": "# Products\n\nSee [awesome remark][awesome] for the products using remark.\n\n[awesome]: https://github.com/remarkjs/awesome"
},
{
"path": "license",
"chars": 1094,
"preview": "(The MIT License)\n\nCopyright (c) Titus Wormer <tituswormer@gmail.com>\n\nPermission is hereby granted, free of charge, to "
},
{
"path": "package.json",
"chars": 1750,
"preview": "{\n \"name\": \"remark\",\n \"private\": true,\n \"license\": \"MIT\",\n \"homepage\": \"https://remark.js.org\",\n \"repository\": \"htt"
},
{
"path": "packages/remark/.npmrc",
"chars": 39,
"preview": "ignore-scripts=true\npackage-lock=false\n"
},
{
"path": "packages/remark/index.d.ts",
"chars": 330,
"preview": "/// <reference types=\"remark-parse\" />\n/// <reference types=\"remark-stringify\" />\n\nimport type {Root} from 'mdast'\nimpor"
},
{
"path": "packages/remark/index.js",
"chars": 341,
"preview": "// Note: types exposed from `index.d.ts`\nimport remarkParse from 'remark-parse'\nimport remarkStringify from 'remark-stri"
},
{
"path": "packages/remark/license",
"chars": 1094,
"preview": "(The MIT License)\n\nCopyright (c) Titus Wormer <tituswormer@gmail.com>\n\nPermission is hereby granted, free of charge, to "
},
{
"path": "packages/remark/package.json",
"chars": 1366,
"preview": "{\n \"author\": \"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)\",\n \"bugs\": \"https://github.com/remarkjs/remark"
},
{
"path": "packages/remark/readme.md",
"chars": 11964,
"preview": "# remark\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-url]\n[![Down"
},
{
"path": "packages/remark/tsconfig.json",
"chars": 121,
"preview": "{\n \"extends\": \"../../tsconfig.json\",\n \"references\": [{\"path\": \"../remark-parse/\"}, {\"path\": \"../remark-stringify/\"}]\n}"
},
{
"path": "packages/remark-cli/.npmrc",
"chars": 39,
"preview": "ignore-scripts=true\npackage-lock=false\n"
},
{
"path": "packages/remark-cli/cli.js",
"chars": 996,
"preview": "#!/usr/bin/env node\n\n/**\n * @typedef Pack\n * @property {string} name\n * @property {string} version\n * @property {string}"
},
{
"path": "packages/remark-cli/license",
"chars": 1094,
"preview": "(The MIT License)\n\nCopyright (c) Titus Wormer <tituswormer@gmail.com>\n\nPermission is hereby granted, free of charge, to "
},
{
"path": "packages/remark-cli/package.json",
"chars": 1042,
"preview": "{\n \"author\": \"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)\",\n \"bin\": {\n \"remark\": \"cli.js\"\n },\n \"bug"
},
{
"path": "packages/remark-cli/readme.md",
"chars": 14540,
"preview": "# remark-cli\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-url]\n[!["
},
{
"path": "packages/remark-cli/tsconfig.json",
"chars": 81,
"preview": "{\n \"extends\": \"../../tsconfig.json\",\n \"references\": [{\"path\": \"../remark/\"}]\n}\n"
},
{
"path": "packages/remark-parse/.npmrc",
"chars": 39,
"preview": "ignore-scripts=true\npackage-lock=false\n"
},
{
"path": "packages/remark-parse/index.d.ts",
"chars": 1946,
"preview": "import type {Root} from 'mdast'\nimport type {Extension as FromMarkdownExtension} from 'mdast-util-from-markdown'\nimport "
},
{
"path": "packages/remark-parse/index.js",
"chars": 81,
"preview": "// Note: types exposed from `index.d.ts`.\nexport {default} from './lib/index.js'\n"
},
{
"path": "packages/remark-parse/lib/index.js",
"chars": 1081,
"preview": "/**\n * @import {Root} from 'mdast'\n * @import {Options as FromMarkdownOptions} from 'mdast-util-from-markdown'\n * @impor"
},
{
"path": "packages/remark-parse/license",
"chars": 1094,
"preview": "(The MIT License)\n\nCopyright (c) Titus Wormer <tituswormer@gmail.com>\n\nPermission is hereby granted, free of charge, to "
},
{
"path": "packages/remark-parse/package.json",
"chars": 1936,
"preview": "{\n \"author\": \"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)\",\n \"bugs\": \"https://github.com/remarkjs/remark"
},
{
"path": "packages/remark-parse/readme.md",
"chars": 12099,
"preview": "# remark-parse\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-url]\n["
},
{
"path": "packages/remark-parse/tsconfig.json",
"chars": 39,
"preview": "{\n \"extends\": \"../../tsconfig.json\"\n}\n"
},
{
"path": "packages/remark-stringify/.npmrc",
"chars": 39,
"preview": "ignore-scripts=true\npackage-lock=false\n"
},
{
"path": "packages/remark-stringify/index.d.ts",
"chars": 1341,
"preview": "import type {Root} from 'mdast'\nimport type {Options as ToMarkdownExtension} from 'mdast-util-to-markdown'\nimport type {"
},
{
"path": "packages/remark-stringify/index.js",
"chars": 81,
"preview": "// Note: types exposed from `index.d.ts`.\nexport {default} from './lib/index.js'\n"
},
{
"path": "packages/remark-stringify/lib/index.js",
"chars": 1015,
"preview": "/**\n * @import {Root} from 'mdast'\n * @import {Options as ToMarkdownOptions} from 'mdast-util-to-markdown'\n * @import {P"
},
{
"path": "packages/remark-stringify/license",
"chars": 1094,
"preview": "(The MIT License)\n\nCopyright (c) Titus Wormer <tituswormer@gmail.com>\n\nPermission is hereby granted, free of charge, to "
},
{
"path": "packages/remark-stringify/package.json",
"chars": 1829,
"preview": "{\n \"author\": \"Titus Wormer <tituswormer@gmail.com> (https://wooorm.com)\",\n \"bugs\": \"https://github.com/remarkjs/remark"
},
{
"path": "packages/remark-stringify/readme.md",
"chars": 13296,
"preview": "# remark-stringify\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverage-ur"
},
{
"path": "packages/remark-stringify/tsconfig.json",
"chars": 39,
"preview": "{\n \"extends\": \"../../tsconfig.json\"\n}\n"
},
{
"path": "readme.md",
"chars": 19946,
"preview": "# ![remark][file-logo]\n\n[![Build][badge-build-image]][badge-build-url]\n[![Coverage][badge-coverage-image]][badge-coverag"
},
{
"path": "test.js",
"chars": 11213,
"preview": "import assert from 'node:assert/strict'\nimport {exec as execCallback} from 'node:child_process'\nimport test from 'node:t"
},
{
"path": "tsconfig.json",
"chars": 512,
"preview": "{\n \"compilerOptions\": {\n \"checkJs\": true,\n \"customConditions\": [\"development\"],\n \"declarationMap\": true,\n \""
}
]
About this extraction
This page contains the full source code of the remarkjs/remark GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 45 files (129.9 KB), approximately 36.8k tokens, and a symbol index with 6 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.
Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.