markdown-magic
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/markdown-magic package

    2.5.2 • Public • Published

    Markdown Magic npm-version

    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 demoExample Repo

    Table of Contents

    Click to expand

    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 = {
      matchWord: 'MD-MAGIC-EXAMPLE',
      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('markdown processing 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.

    > 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
    • maxDepth - number - (optional): Max depth of headings. Default 4

    Example:

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

    Default MATCHWORD is AUTO-GENERATED-CONTENT


    > 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
    • 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:

    <!-- 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 -->
     <!-- AUTO-GENERATED-CONTENT:START (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
     <!-- AUTO-GENERATED-CONTENT:END -->

    Default MATCHWORD is AUTO-GENERATED-CONTENT


    > FILE

    Get local file contents.

    Options:

    • src: The relative path to the file to pull in

    Example:

    <!-- AUTO-GENERATED-CONTENT:START (FILE:src=./path/to/file) -->
    This content will be dynamically replaced from the local 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 replaced from the remote url
    <!-- AUTO-GENERATED-CONTENT:END -->

    Default MATCHWORD is AUTO-GENERATED-CONTENT


    Inline transforms

    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:

    <!-- AUTO-GENERATED-CONTENT:START (FILE:src=./path/to/file) -->xyz<!-- AUTO-GENERATED-CONTENT:END -->

    🔌 Markdown magic plugins

    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 markdownMagic = require('../index')
    // const markdownMagic = require('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('doxxx').parseComments(fileContents, { raw: true, skipSingleStar: true })
          let updatedContent = ''
          docBlocs.forEach((data) => {
            updatedContent += `${data.description.full}\n\n`
          })
          return updatedContent.replace(/^\s+|\s+$/g, '')
        },
        INLINE_EXAMPLE: () => {
          return '**⊂◉‿◉つ**'
        },
        /* 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')
    })

    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

    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

    License

    MIT © DavidWells

    Usage examples

    Keywords

    none

    Install

    npm i markdown-magic

    DownloadsWeekly Downloads

    20,508

    Version

    2.5.2

    License

    MIT

    Unpacked Size

    249 kB

    Total Files

    36

    Last publish

    Collaborators

    • davidwells