markdown-magic-block
Advanced tools
Automatically update markdown files with content from external sources
✨ Add a little magic to your markdown ✨
Markdown magic uses comment blocks in markdown files to automatically sync or transform its contents.
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.
npm install markdown-magic --save-dev
import path from 'path'
import markdownMagic from 'markdown-magic'
const markdownPath = path.join(__dirname, 'README.md')
markdownMagic(markdownPath)
markdownMagic(filePath, config, callback)
filePaths - String or Array - Path or glob pattern. Uses globby patternsconfig - See configuration options belowcallback - callback to run after markdown updatestransforms - 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
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')
}
}
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 falsecollapse - boolean - (optional): Collapse the table of contents in a detail accordian. Default falsecollapseText - string - (optional): Text the toc accordian summaryexcludeText - string - (optional): Text to exclude in the table of contents. Default Table of ContentsmaxDepth - number - (optional): Max depth of headings. Default 4Example:
<!-- AUTO-GENERATED-CONTENT:START (TOC) -->
toc will be generated here
<!-- AUTO-GENERATED-CONTENT:END -->
Default MATCHWORD is AUTO-GENERATED-CONTENT
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 livessyntax (optional): Syntax will be inferred by fileType if not specifiedheader (optional): Will add header comment to code snippet. Useful for pointing to relative source directory or adding live doc linkslines (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 belowExample:
<!-- 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
Get local file contents.
Options:
src: The relative path to the file to pull inExample:
<!-- 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
Get any remote Data and put in markdown
Options:
url: The URL of the remote content to pull inExample:
<!-- 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
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 -->
peerDependencies includedpackage.json scripts with descriptionsprettierpackage.jsonMarkdown 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')
})
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
json file and converts it into a github flavored markdown tableView 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
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
FAQs
Automatically update markdown files with content from external sources
We found that markdown-magic-block demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.