✨ Add a little magic to your markdown! ✨

Markdown magic uses comment blocks in markdown files to automatically sync or transform its contents.

• Automatically keep markdown files up to date from local or remote code sources
• Transform markdown content with custom transform functions
• Render markdown with any template engine
• Automatically generate a table of contents
• ... etc

The comments markdown magic uses are hidden in markdown and when viewed as HTML.

This README.md is generated with markdown-magic view the raw file to see how.

Video demo • Example Repo

• About
• Install
• Usage
  • Running via CLI
  • Running programmatically
• Syntax Examples
  • Basic
  • Curly braces
  • Square brackets
  • Parentheses
  • Functions
  • API
    • MarkdownMagicOptions
    • OutputConfig
    • MarkdownMagicResult
• Transforms
  • > TOC
  • > CODE
  • > FILE
  • > REMOTE
  • > fileTree
  • > install
• Inline transforms
• Plugins
• Legacy v1 & v2 plugins
• Adding Custom Transforms
• Plugin Example
• Other usage examples
• Custom Transform Demo
• Usage examples
• Misc Markdown helpers
• Prior Art
• License

Via npm

npm install markdown-magic --save-dev

Via binary (no Node.js required)

Download the prebuilt binary for your platform from GitHub Releases:

# macOS (Apple Silicon)
curl -fsSL https://github.com/DavidWells/markdown-magic/releases/latest/download/md-magic-darwin-arm64 -o md-magic
chmod +x md-magic

# macOS (Intel)
curl -fsSL https://github.com/DavidWells/markdown-magic/releases/latest/download/md-magic-darwin-x64 -o md-magic
chmod +x md-magic

# Linux (x64)
curl -fsSL https://github.com/DavidWells/markdown-magic/releases/latest/download/md-magic-linux-x64 -o md-magic
chmod +x md-magic

# Linux (ARM64)
curl -fsSL https://github.com/DavidWells/markdown-magic/releases/latest/download/md-magic-linux-arm64 -o md-magic
chmod +x md-magic

Use comment blocks in your markdown

Example:

<!-- docs remote url=http://url-to-raw-md-file.md -->
This content will be dynamically replaced from the remote url
<!-- /docs -->

Then run markdown-magic via it's CLI or programmatically.

Run markdown --help to see all available CLI options

markdown
# or
md-magic

CLI usage example with options

md-magic --file '**/*.md' --config ./config.file.js

In NPM scripts, npm run docs would run the markdown magic and parse all the .md files in the directory.

"scripts": {
  "docs": "md-magic --file '**/*.md'"
},

If you have an md.config.js or markdown.config.js file where markdown-magic is invoked, it will automatically use that as the configuration unless otherwise specified by --config flag.

const { markdownMagic } = require('../src')

/* By default all .md files in cwd will be processed */
markdownMagic().then((results) => {
  console.log('result keys', Object.keys(results))
})

import path from 'path'
import markdownMagic from 'markdown-magic'

// Process a Single File
const markdownPath = path.join(__dirname, 'README.md')
markdownMagic(markdownPath)

Use the prebuilt binary to automatically update markdown files on push:

name: Update Markdown

on:
  push:
    paths:
      - '**.md'
      - 'src/**'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Download md-magic
        run: |
          curl -fsSL https://github.com/DavidWells/markdown-magic/releases/latest/download/md-magic-linux-x64 -o md-magic
          chmod +x md-magic

      - name: Run markdown-magic
        run: ./md-magic --files '**/*.md'

      - name: Commit changes
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git diff --staged --quiet || git commit -m "docs: update markdown"
          git push

• markdown-code-inject - Inject code snippets into markdown
• markdown-autodocs - Auto-generate docs from code

There are various syntax options. Choose your favorite.

openWord transformName [opts]

<!-- docs transformName optionOne='hello' optionTwo='there' -->
content to be replaced
<!-- /docs -->

openWord {transformName} [opts]

<!-- docs {transformName} optionOne='hello' optionTwo='there' -->
content to be replaced
<!-- /docs -->

openWord [transformName] [opts]

<!-- docs [transformName] optionOne='hello' optionTwo='there' -->
content to be replaced
<!-- /docs -->

openWord (transformName) [opts]

<!-- docs (transformName) optionOne='hello' optionTwo='there' -->
content to be replaced
<!-- /docs -->

openWord transformName([opts])

<!-- docs transformName(
  foo='bar'
  baz=['qux', 'quux']
) -->
content to be replaced
<!-- /docs -->

Markdown Magic Instance

markdownMagic(globOrOpts, options)

Returns

Promise<MarkdownMagicResult>

Example

markdownMagic(['**.**.md'], options).then((result) => {
  console.log(`Processing complete`, result)
})

Configuration for markdown magic

Below is the main config for markdown-magic

Remote fetch cache options

Optional output configuration

Result of markdown processing

Markdown Magic comes with a couple of built-in transforms for you to use or you can extend it with your own transforms. See 'Custom Transforms' below.

Generate table of contents from markdown file

Options:

• firstH1 - boolean - (optional): Show first h1 of doc in table of contents. Default false
• collapse - boolean - (optional): Collapse the table of contents in a detail accordion. Default false
• collapseText - string - (optional): Text the toc accordion summary
• excludeText - string - (optional): Text to exclude in the table of contents. Default Table of Contents
• maxDepth - number - (optional): Max depth of headings. Default 4

Example:

<!-- docs TOC -->
toc will be generated here
<!-- /docs -->

Default matchWord is docs

Get code from file or URL and put in markdown

Options:

• src: The relative path to the code to pull in, or the URL where the raw code lives
• syntax (optional): Syntax will be inferred by fileType if not specified
• header (optional): Will add header comment to code snippet. Useful for pointing to relative source directory or adding live doc links
• lines (optional): a range with lines of code which will then be replaced with code from the file. The line range should be defined as: "lines=startLine-EndLine" (for example: "lines=22-44"). Please see the example below

Example:

<!-- docs CODE src="./relative/path/to/code.js" -->
This content will be dynamically replaced with code from the file
<!-- /docs -->

 <!-- docs CODE src="./relative/path/to/code.js" lines=22-44 -->
 This content will be dynamically replaced with code from the file lines 22 through 44
 <!-- /docs -->

Default matchWord is docs

Get local file contents.

Options:

• src: The relative path to the file to pull in
• sections: Comma-separated list or array of markdown section headings to include
• section: Single markdown section heading to include
• headings: Array of markdown heading levels to include, such as headings={[2,3]}
• removeLeadingH1: Remove the first H1 from imported markdown
• shiftHeaders: Shift imported markdown headings up or down by a number

Example:

<!-- docs FILE src=./path/to/file -->
This content will be dynamically replaced from the local file
<!-- /docs -->

Default matchWord is docs

Get any remote Data and put in markdown

Options:

• url: The URL of the remote content to pull in
• src: Alias for url
• githubToken: Optional token value for private GitHub files. Only used when private GitHub reads are enabled.
• useGhCli: For GitHub URLs, allow fallback to gh api when private GitHub reads are enabled. Default: true
• preferGhCli: Try gh api before the GitHub contents API. Default: false
• sections: Comma-separated list or array of markdown section headings to include
• section: Single markdown section heading to include
• headings: Array of markdown heading levels to include, such as headings={[2,3]}
• removeLeadingH1: Remove the first H1 from imported markdown
• shiftHeaders: Shift imported markdown headings up or down by a number

Example:

<!-- docs REMOTE url=http://url-to-raw-md-file.md -->
This content will be dynamically replaced from the remote url
<!-- /docs -->

GitHub blob and raw.githubusercontent.com file URLs are resolved with GitHub-aware fallbacks. Public files use anonymous raw GitHub content first. Private files are opt-in and can be fetched with GITHUB_ACCESS_TOKEN, GITHUB_TOKEN, githubToken, or an authenticated GitHub CLI session only when allowPrivateGithub is enabled:

<!-- docs REMOTE
  src='https://github.com/owner/private-repo/blob/main/README.md'
  removeLeadingH1
-->
Existing content is kept if failOnMissingRemote is false.
<!-- /docs -->

Enable private GitHub reads from config:

module.exports = {
  allowPrivateGithub: true
}

Or for a single CLI run:

md-magic --allow-private-github --files README.md

To use local GitHub CLI auth instead of a token, run gh auth status first. Set MARKDOWN_MAGIC_GH_CLI=0 to disable gh api fallback in CI or locked-down environments.

Remote requests are logged once per unique URL as they are attempted. Set logRemoteRequests: false in config to disable this output.

Successful remote responses are cached outside the project in the user's OS cache directory by default. Normal responses are reused for 5 minutes. GitHub files pinned to a full 40-character commit SHA use a longer immutable cache TTL. Set remoteCache: false or remoteCache: { enabled: false } to disable the cache, or pass --no-cache / --no-remote-cache for a single CLI run. Set remoteCache.cachePrivate: false to avoid persisting authenticated private GitHub responses to disk. Cache hits are logged as Getting remote (from cache): unless remoteCache.logHits or logRemoteRequests is disabled.

Default matchWord is docs

Generate a file tree table of contents

Options:

• src (optional): The directory path to generate the file tree for. Default . (current directory)
• maxDepth (optional): Maximum depth to traverse in the directory tree. Default 3
• includeFiles (optional): Whether to include files in the tree or just directories. Default true
• exclude (optional): Array of glob patterns to exclude from the tree. Default []
• showSize (optional): Whether to show file sizes. Default false
• format (optional): Output format: "tree" or "list". Default "tree"

Example:

<!-- docs fileTree src="./src" maxDepth=2 -->
file tree will be generated here
<!-- /docs -->

Example Output (tree format):

└── src/
    ├── transforms/
    │   ├── code/
    │   │   ...
    │   ├── fileTree.js
    │   ├── index.js
    │   └── toc.js
    ├── utils/
    │   ├── fs.js
    │   ├── logs.js
    │   └── text.js
    └── index.js

Example Output (list format):

- **src/**
  - **transforms/**
    - **code/**
      - ...
    - fileTree.js
    - index.js
    - toc.js
  - **utils/**
    - fs.js
    - logs.js
    - text.js
  - index.js

Example with file sizes:

└── src/
    ├── index.js (15.2 KB)
    └── package.json (552 B)

Default matchWord is docs

Generate installation instructions in a markdown table format

Options:

• packageName (optional): The name of the package to install. If not provided, will try to read from package.json
• isDev (optional): Whether to install the package as a dev dependency. Default false
• header (optional): The header to use for the installation instructions. Default # Installation
• body (optional): The body to use for the installation instructions. Default Install the \${packageName}` cli using your favorite package manager.`

Example:

<!-- docs install -->
Installation instructions will be generated here
<!-- /docs -->

Default matchWord is docs

Any transform, including custom transforms can be used inline as well to insert content into paragraphs and other places.

The face symbol 👉 ⊂◉‿◉つ is auto generated inline.

Example:

<!-- docs (FILE:src=./path/to/file) -->xyz<!-- /docs -->

These plugins are maintained and compatible with the latest markdown-magic v4+ plugin API.

• dependency-table - Add a table of dependencies with links to their repositories, version information, and a short description
• directory-tree - Add a directory tree to markdown files
• engines - Print the engines list from package.json
• install-command - Add an install command to markdown files with peerDependencies included
• last-modified - Print the last modified date (from git) for a given file
• package-scripts - Add a table of package.json scripts with descriptions
• prettier - Format code blocks with prettier
• subpackage-list - Add a list of all subpackages (great for monorepos, e.g. Lerna or pnpm)
• template - Add Lodash template support
• version-badge - Add a badge with the latest version of the project

These plugins work with older versions of markdown-magic. Adapting them to the newer plugin syntax should be pretty straight forward.

• wordcount - Add wordcount to markdown files
• github-contributors - List out the contributors of a given repository
• jsdoc - Adds jsdoc comment support
• build-badge - Update branch badges to auto-magically point to current branches.
• package-json - Add the package.json properties to markdown files
• figlet - Add FIGfont text to markdown files
• local-image - plugin to add local images to markdown
• markdown-magic-build-badge - A plugin to update your branch badges to point to correct branch status
• markdown-magic-json-path – Extract and insert specific values from any JSON file into your Markdown documents.

Markdown Magic is extendable via plugins.

Plugins allow developers to add new transforms to the config.transforms object. This allows for things like using different rendering engines, custom formatting, or any other logic you might want.

Plugins run in order of registration.

The below code is used to generate this markdown file via the plugin system.

const path = require('path')
const { readFileSync } = require('fs')
const { parseComments } = require('doxxx')
const { markdownMagic } = require('../src')
const { deepLog } = require('../src/utils/logs')

const config = {
  matchWord: 'MD-MAGIC-EXAMPLE', // default matchWord is AUTO-GENERATED-CONTENT
  transforms: {
    /* Match <!-- AUTO-GENERATED-CONTENT:START (customTransform:optionOne=hi&optionOne=DUDE) --> */
    customTransform({ content, options }) {
      console.log('original content in comment block', content)
      console.log('options defined on transform', options)
      // options = { optionOne: hi, optionOne: DUDE}
      return `This will replace all the contents of inside the comment ${options.optionOne}`
    },
    /* Match <!-- AUTO-GENERATED-CONTENT:START JSDocs path="../file.js" --> */
    JSDocs(markdownMagicPluginAPI) {
      const { options } = markdownMagicPluginAPI
      const fileContents = readFileSync(options.path, 'utf8')
      const docBlocs = parseComments(fileContents, { skipSingleStar: true })
        .filter((item) => {
          return !item.isIgnored
        })
        /* Remove empty comments with no tags */
        .filter((item) => {
          return item.tags.length
        })
        /* Remove inline type defs */
        .filter((item) => {
          return item.description.text !== ''
        })
        /* Sort types to end */
        .sort((a, b) => {
          if (a.type && !b.type) return 1
          if (!a.type && b.type) return -1
          return 0
        })

      docBlocs.forEach((data) => {
        // console.log('data', data)
        delete data.code
      })
      // console.log('docBlocs', docBlocs)

      if (docBlocs.length === 0) {
        throw new Error('No docBlocs found')
      }

      // console.log(docBlocs.length)
      let updatedContent = ''
      docBlocs.forEach((data) => {
        if (data.type) {
          updatedContent += `#### \`${data.type}\`\n\n`
        }

        updatedContent += `${data.description.text}\n`

        if (data.tags.length) {
         let table =  '| Name | Type | Description |\n'
          table += '|:---------------------------|:---------------:|:-----------|\n'
          data.tags.filter((tag) => {
            if (tag.tagType === 'param') return true
            if (tag.tagType === 'property') return true
            return false
          }).forEach((tag) => {
            const optionalText = tag.isOptional ? ' (optional) ' : ' '
            const defaultValueText = (typeof tag.defaultValue !== 'undefined') ? ` Default: \`${tag.defaultValue}\` ` : ' '
            table += `| \`${tag.name}\`${optionalText}`
            table += `| \`${tag.type.replace('|', 'or')}\` `
            table += `| ${tag.description.replace(/\.\s?$/, '')}.${defaultValueText}|\n`
          })
          updatedContent+= `\n${table}\n`

          const returnValues = data.tags.filter((tag) => tag.tagType === 'returns')
          if (returnValues.length) {
            returnValues.forEach((returnValue) => {
              updatedContent += `**Returns**\n\n`
              updatedContent += `\`${returnValue.type}\`\n\n`
            })
          }

          const examples = data.tags.filter((tag) => tag.tagType === 'example')
          if (examples.length) {
            examples.forEach((example) => {
              updatedContent += `**Example**\n\n`
              updatedContent += `\`\`\`js\n${example.tagValue}\n\`\`\`\n\n`
            })
          }
        }
      })
      return updatedContent.replace(/^\s+|\s+$/g, '')
    },
    INLINE_EXAMPLE: () => {
      return '**⊂◉‿◉つ**'
    },
    lolz() {
      return `This section was generated by the cli config md.config.js file`
    },
    /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
    pluginExample: require('./plugin-example')({ addNewLine: true }),
    /* Include plugins from NPM */
    // count: require('markdown-magic-wordcount'),
    // github: require('markdown-magic-github-contributors')
  }
}

const markdownPath = path.join(__dirname, '..', 'README.md')
markdownMagic(markdownPath, config, () => {
  console.log('Docs ready')
})

Plugins must return a transform function with the following signature.

return function myCustomTransform (content, options)

/* Custom Transform Plugin example */
module.exports = function customPlugin(pluginOptions) {
  // set plugin defaults
  const defaultOptions = {
    addNewLine: false
  }
  const userOptions = pluginOptions || {}
  const pluginConfig = Object.assign(defaultOptions, userOptions)
  // return the transform function
  return function myCustomTransform ({ content, options }) {
    const newLine = (pluginConfig.addNewLine) ? '\n' : ''
    const updatedContent = content + newLine
    return updatedContent
  }
}

View the raw file file and run npm run docs to see this plugin run

This content is altered by the pluginExample plugin registered in examples/generate-readme.js

• With Github Actions
• Serverless Plugin Repo this example takes a json file and converts it into a github flavored markdown table
• MochaJS
• tc39/agendas - code
• moleculerjs/moleculer-addons
• good-first-issue
• navikt/nav-frontend-moduler
• country-flags-svg
• react-typesetting
• and many more!

View the raw source of this README.md file to see the comment block and see how the customTransform function in examples/generate-readme.js works

This will replace all the contents of inside the comment DUDE

• Projects using markdown-magic
• Examples in md

• https://github.com/azu/markdown-function

This was inspired by Kent C Dodds and jfmengels's all contributors cli project.

MIT © DavidWells