Markdown Magic

✨ Add a little magic to your markdown ✨

About

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

Click to expand

About
Install
Usage
- API
- Configuration Options
CLI Usage
Transforms
🔌 Third Party Plugins
Adding Custom Transforms
Plugin Example
Other usage examples
Custom Transform Demo
Prior Art
License

Install

npm install markdown-magic --save-dev

Usage

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

const markdownPath = path.join(__dirname, 'README.md')
markdownMagic(markdownPath)

API

markdownMagic(filePath, config, callback)

filePaths - String or Array - Path or glob pattern. Uses globby patterns
config - See configuration options below
callback - callback to run after markdown updates

Configuration Options

transforms - object - (optional) Custom commands to transform block contents, see transforms & custom transforms sections below.
outputDir - string - (optional) Change output path of new content. Default behavior is replacing the original file
matchWord - string - (optional) Comment pattern to look for & replace inner contents. Default AUTO-GENERATED-CONTENT
DEBUG - Boolean - (optional) set debug flag to true to inspect the process

CLI Usage

You can use markdown-magic as a CLI command. Run markdown --help to see all available CLI options

markdown --help
# or
md-magic

This is useful for adding the package quickly to your package.json npm scripts

CLI usage example with options

md-magic --path '**/*.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 --path '**/*.md' --ignore 'node_modules'"
},

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

/* CLI markdown.config.js file example */
module.exports = {
  transforms: {
    /* Match <!-- AUTO-GENERATED-CONTENT:START (LOLZ) --> */
    LOLZ(content, options) {
      return `This section was generated by the cli config markdown.config.js file`
    }
  },
  callback: function () {
    console.log('done')
  }
}

Transforms

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.

🔀 CODE

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

Example:

<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js) -->
This content will be dynamically replaced with code from the file
<!-- AUTO-GENERATED-CONTENT:END -->

Default MATCHWORD is AUTO-GENERATED-CONTENT

🔀 REMOTE

Get any remote Data and put in markdown

Options:

url: The URL of the remote content to pull in

Example:

<!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=http://url-to-raw-md-file.md) -->
This content will be dynamically replace from the remote url
<!-- AUTO-GENERATED-CONTENT:END -->

Default MATCHWORD is AUTO-GENERATED-CONTENT

🔀 TOC

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 accordian. Default false
collapseText - string - (optional): Text the toc accordian summary
excludeText - string - (optional): Text to exclude in the table of contents. Default Table of Contents

Example:

<!-- AUTO-GENERATED-CONTENT:START (TOC) -->
toc will be generated here
<!-- AUTO-GENERATED-CONTENT:END -->

Default MATCHWORD is AUTO-GENERATED-CONTENT

🔌 Third Party Plugins

wordcount - Add wordcount to markdown files
github-contributors - List out the contributors of a given repository
directory-tree - Add directory tree to markdown files
install-command - Add install command to markdown files with peerDependencies included
subpackage-list - Add list of all subpackages (great for projects that use Lerna)
version-badge - Add a badge with the latest version of the project
template - Add Lodash template support
dependency-table - Add a table of dependencies with links to their repositories, version information, and a short description
package-scripts - Add a table of package.json scripts with descriptions
prettier - Format code blocks with prettier
engines - Print engines list from package.json
jsdoc - Adds jsdoc comment support
package-json - Add the package.json properties to markdown files

Adding Custom Transforms

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 fs = require('fs')
const path = require('path')
const execSync = require('child_process').execSync
const markdownMagic = require('../index') // 'markdown-magic'

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 (RENDERDOCS:path=../file.js) --> */
    RENDERDOCS(content, options) {
      const fileContents = fs.readFileSync(options.path, 'utf8')
      const docBlocs = require('dox').parseComments(fileContents, { raw: true, skipSingleStar: true })
      let updatedContent = ''
      docBlocs.forEach((data) => {
        updatedContent += `${data.description.full}\n\n`
      })
      return updatedContent.replace(/^\s+|\s+$/g, '')
    },
    /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
    pluginExample: require('./plugin-example')({ addNewLine: true }),
    /* Plugins from npm */
    // count: require('markdown-magic-wordcount'),
    // github: require('markdown-magic-github-contributors')
  }
}

/* This example callback automatically updates Readme.md and commits the changes */
const callback = function autoGitCommit(err, output) {
  // output is array of file information
  output.forEach(function(data) {
    const mdPath = data.outputFilePath
    if(!mdPath) return false
    const gitAdd = execSync(`git add ${mdPath}`, {}, (error) => {
      if (error) console.warn(error)
      const msg = `${mdPath} automatically updated by markdown-magic`
      const gitCommitCommand = `git commit -m '${msg}' --no-verify`
      execSync(gitCommitCommand, {}, (err) => {
        if (err) console.warn(err)
        console.log('git commit automatically ran. Push up your changes!')
      })
    })
  })
}

const markdownPath = path.join(__dirname, '..', 'README.md')
markdownMagic(markdownPath, config, callback)

Plugin Example

Plugins must return a transform function with the following signature.

return function myCustomTransform (content, options)

/* Custom Transform Plugin example */
const merge = require('deepmerge')
module.exports = function customPlugin(pluginOptions) {
  // set plugin defaults
  const defaultOptions = {
    addNewLine: false
  }
  const userOptions = pluginOptions || {}
  const pluginConfig = merge(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

Other usage examples

Serverless Plugin Repo this example takes a json file and converts it into a github flavored markdown table

Custom Transform Demo

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

Prior Art

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

This section was generated by the cli config markdown.config.js file

tsiq-swyx/markdown-magic

Markdown Magic

About

Table of Contents

Install

Usage

API

Configuration Options

CLI Usage

Transforms

🔀 CODE

🔀 REMOTE

🔀 TOC

🔌 Third Party Plugins

Adding Custom Transforms

Plugin Example

Other usage examples

Custom Transform Demo

Prior Art

License