markdown-magic

Markdown Magic

Automatically keep markdown files up to date from source code or via external sources.

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

Install

npm install markdown-magic --save-dev

Usage

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

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

Function signature

markdownMagic(filename, config, callback)
// Configuration and callback are optional params

Configuration Options

matchWord - string - (optional) Comment pattern to look for & replace inner contents. Default AUTO-GENERATED-CONTENT

commands - object - (optional) Custom commands to transform block contents, see configuration options below.

outputPath - string - (optional) Change output path of new content. Default behavior is replacing the original file

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:

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

---

- REMOTE

Get any remote Data and put in markdown

Options:

• url: The URL of the remote content to pull in

Example:

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

---

Custom Transforms

Markdown Magic is extendable via plugins.

Plugins allow developers to add new transforms, use different rendering engines or any other logic you might want in config.commands.

This code is used to generate this markdown file:

const fs = require('fs')
const path = require('path')
const dox = require('dox')
const execSync = require('child_process').execSync
const markdownMagic = require('../index') // 'markdown-magic'

const config = {
  commands: {
    /* Update the content in comment in .md matching
       AUTO-GENERATED-CONTENT (customTransform:optionOne=hi&optionOne=DUDE)
    */
    customTransform(content, options) {
      console.log('original innerContent', content)
      console.log(options) // { optionOne: hi, optionOne: DUDE}
      return `This will replace all the contents of inside the comment ${options.optionOne}`
    },
    /* Update the content in comment in .md matching
      AUTO-GENERATED-CONTENT (RENDERDOCS:path=../file.js)
    */
    RENDERDOCS(content, options) {
      const filePath = path.join(__dirname, options.path)
      const contents = fs.readFileSync(filePath, 'utf8')
      const docBlocs = dox.parseComments(contents, { raw: true, skipSingleStar: true })
      let updatedContent = ''
      docBlocs.forEach((data) => {
        updatedContent += `${data.description.full}\n\n`
      })
      return updatedContent.replace(/^\s+|\s+$/g, '')
    },
    pluginExample: require('./plugin-example')({ addNewLine: true })
  }
}

/* This example callback automatically updates Readme.md and commits the changes */
const callback = function autoGitCommit(updatedContent, outputConfig) {
  const mdPath = outputConfig.outputPath
  const gitAdd = execSync(`git add ${mdPath}`, {}, (error) => {
    if (error) console.warn(error)
    console.log('git add complete')
    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:

/**
 * 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 (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 Community Plugin Repo this example takes a json file and converts it into a github flavored markdown table

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.