1 | # Markdown Magic [![npm-version][npm-badge]][npm-link]
|
2 |
|
3 | ✨ Add a little magic to your markdown ✨
|
4 |
|
5 | ## About
|
6 |
|
7 | <img align="right" width="200" height="183" src="https://cloud.githubusercontent.com/assets/532272/21507867/3376e9fe-cc4a-11e6-9350-7ec4f680da36.gif">Markdown magic uses comment blocks in markdown files to automatically sync or transform its contents.
|
8 |
|
9 | - Automatically keep markdown files up to date from local or remote code sources
|
10 | - Transform markdown content with custom transform functions
|
11 | - Render markdown with any template engine
|
12 | - Automatically generate a table of contents
|
13 | - ... etc
|
14 |
|
15 | The comments markdown magic uses are hidden in markdown and when viewed as HTML.
|
16 |
|
17 | This `README.md` is generated with `markdown-magic` [view the raw file](https://raw.githubusercontent.com/DavidWells/markdown-magic/master/README.md) to see how.
|
18 |
|
19 | [Video demo](http://www.youtube.com/watch?v=4V2utrvxwJ8) • [Example Repo](https://github.com/DavidWells/repo-using-markdown-magic)
|
20 |
|
21 | ## Table of Contents
|
22 |
|
23 | <details>
|
24 | <summary>Click to expand</summary>
|
25 |
|
26 | - [About](#about)
|
27 | - [Install](#install)
|
28 | - [Usage](#usage)
|
29 | - [API](#api)
|
30 | - [Configuration Options](#configuration-options)
|
31 | - [CLI Usage](#cli-usage)
|
32 | - [Transforms](#transforms)
|
33 | - [> TOC](#-toc)
|
34 | - [> CODE](#-code)
|
35 | - [> REMOTE](#-remote)
|
36 | - [🔌 Markdown magic plugins](#-markdown-magic-plugins)
|
37 | - [Adding Custom Transforms](#adding-custom-transforms)
|
38 | - [Plugin Example](#plugin-example)
|
39 | - [Other usage examples](#other-usage-examples)
|
40 | - [Custom Transform Demo](#custom-transform-demo)
|
41 | - [Prior Art](#prior-art)
|
42 | - [License](#license)
|
43 | - [Usage examples](#usage-examples)
|
44 |
|
45 | </details>
|
46 |
|
47 |
|
48 | ## Install
|
49 |
|
50 | ```bash
|
51 | npm install markdown-magic --save-dev
|
52 | ```
|
53 |
|
54 | ## Usage
|
55 |
|
56 |
|
57 | ```js
|
58 | import path from 'path'
|
59 | import markdownMagic from 'markdown-magic'
|
60 |
|
61 | const markdownPath = path.join(__dirname, 'README.md')
|
62 | markdownMagic(markdownPath)
|
63 | ```
|
64 |
|
65 |
|
66 |
|
67 |
|
68 | - Do not remove or modify this section -->
|
69 | ### API
|
70 | ```js
|
71 | markdownMagic(filePath, config, callback)
|
72 | ```
|
73 | - `filePaths` - *String or Array* - Path or glob pattern. Uses [globby patterns](https://github.com/sindresorhus/multimatch/blob/master/test.js)
|
74 | - `config` - See configuration options below
|
75 | - `callback` - callback to run after markdown updates
|
76 |
|
77 |
|
78 |
|
79 | - Do not remove or modify this section -->
|
80 | ### Configuration Options
|
81 |
|
82 | - `transforms` - *object* - (optional) Custom commands to transform block contents, see transforms & custom transforms sections below.
|
83 |
|
84 | - `outputDir` - *string* - (optional) Change output path of new content. Default behavior is replacing the original file
|
85 |
|
86 | - `matchWord` - *string* - (optional) Comment pattern to look for & replace inner contents. Default `AUTO-GENERATED-CONTENT`
|
87 |
|
88 | - `DEBUG` - *Boolean* - (optional) set debug flag to `true` to inspect the process
|
89 |
|
90 |
|
91 | ## CLI Usage
|
92 |
|
93 | You can use `markdown-magic` as a CLI command. Run `markdown --help` to see all available CLI options
|
94 |
|
95 | ```bash
|
96 | markdown --help
|
97 | # or
|
98 | md-magic
|
99 | ```
|
100 |
|
101 | This is useful for adding the package quickly to your `package.json` npm scripts
|
102 |
|
103 | CLI usage example with options
|
104 |
|
105 | ```bash
|
106 | md-magic --path '**/*.md' --config ./config.file.js
|
107 | ```
|
108 |
|
109 | In NPM scripts, `npm run docs` would run the markdown magic and parse all the `.md` files in the directory.
|
110 |
|
111 | ```json
|
112 | "scripts": {
|
113 | "docs": "md-magic --path '**/*.md' --ignore 'node_modules'"
|
114 | },
|
115 | ```
|
116 |
|
117 | 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.
|
118 |
|
119 |
|
120 |
|
121 | ```js
|
122 | /* CLI markdown.config.js file example */
|
123 | module.exports = {
|
124 | matchWord: 'MD-MAGIC-EXAMPLE',
|
125 | transforms: {
|
126 | /* Match <!-- AUTO-GENERATED-CONTENT:START (LOLZ) --> */
|
127 | LOLZ(content, options) {
|
128 | return `This section was generated by the cli config markdown.config.js file`
|
129 | }
|
130 | },
|
131 | callback: function () {
|
132 | console.log('markdown processing done')
|
133 | }
|
134 | }
|
135 | ```
|
136 |
|
137 |
|
138 | ## Transforms
|
139 |
|
140 | 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.
|
141 |
|
142 |
|
143 | ### > TOC
|
144 |
|
145 | Generate table of contents from markdown file
|
146 |
|
147 | **Options:**
|
148 | - `firsth1` - *boolean* - (optional): Show first h1 of doc in table of contents. Default `false`
|
149 | - `collapse` - *boolean* - (optional): Collapse the table of contents in a detail accordian. Default `false`
|
150 | - `collapseText` - *string* - (optional): Text the toc accordian summary
|
151 | - `excludeText` - *string* - (optional): Text to exclude in the table of contents. Default `Table of Contents`
|
152 | - `maxDepth` - *number* - (optional): Max depth of headings. Default 4
|
153 |
|
154 | **Example:**
|
155 | ```md
|
156 | <!-- AUTO-GENERATED-CONTENT:START (TOC) -->
|
157 | toc will be generated here
|
158 | <!-- AUTO-GENERATED-CONTENT:END -->
|
159 | ```
|
160 |
|
161 | Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
|
162 |
|
163 | ---
|
164 |
|
165 | ### > CODE
|
166 |
|
167 | Get code from file or URL and put in markdown
|
168 |
|
169 | **Options:**
|
170 | - `src`: The relative path to the code to pull in, or the `URL` where the raw code lives
|
171 | - `syntax` (optional): Syntax will be inferred by fileType if not specified
|
172 | - `header` (optional): Will add header comment to code snippet. Useful for pointing to relative source directory or adding live doc links
|
173 | - `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
|
174 |
|
175 | **Example:**
|
176 | ```md
|
177 | <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js) -->
|
178 | This content will be dynamically replaced with code from the file
|
179 | <!-- AUTO-GENERATED-CONTENT:END -->
|
180 | ```
|
181 |
|
182 | ```md
|
183 | <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js&lines=22-44) -->
|
184 | This content will be dynamically replaced with code from the file lines 22 through 44
|
185 | <!-- AUTO-GENERATED-CONTENT:END -->
|
186 | ```
|
187 |
|
188 | Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
|
189 |
|
190 | ---
|
191 |
|
192 | ### > REMOTE
|
193 |
|
194 | Get any remote Data and put in markdown
|
195 |
|
196 | **Options:**
|
197 | - `url`: The URL of the remote content to pull in
|
198 |
|
199 | **Example:**
|
200 | ```md
|
201 | <!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=http://url-to-raw-md-file.md) -->
|
202 | This content will be dynamically replace from the remote url
|
203 | <!-- AUTO-GENERATED-CONTENT:END -->
|
204 | ```
|
205 |
|
206 | Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
|
207 |
|
208 | ---
|
209 |
|
210 |
|
211 | ## 🔌 Markdown magic plugins
|
212 |
|
213 | * [wordcount](https://github.com/DavidWells/markdown-magic-wordcount/) - Add wordcount to markdown files
|
214 | * [github-contributors](https://github.com/DavidWells/markdown-magic-github-contributors) - List out the contributors of a given repository
|
215 | * [directory-tree](https://github.com/camacho/markdown-magic-directory-tree) - Add directory tree to markdown files
|
216 | * [install-command](https://github.com/camacho/markdown-magic-install-command) - Add install command to markdown files with `peerDependencies` included
|
217 | * [subpackage-list](https://github.com/camacho/markdown-magic-subpackage-list) - Add list of all subpackages (great for projects that use [Lerna](https://github.com/lerna/lerna))
|
218 | * [version-badge](https://github.com/camacho/markdown-magic-version-badge) - Add a badge with the latest version of the project
|
219 | * [template](https://github.com/camacho/markdown-magic-template) - Add Lodash template support
|
220 | * [dependency-table](https://github.com/camacho/markdown-magic-dependency-table) - Add a table of dependencies with links to their repositories, version information, and a short description
|
221 | * [package-scripts](https://github.com/camacho/markdown-magic-package-scripts) - Add a table of `package.json` scripts with descriptions
|
222 | * [prettier](https://github.com/camacho/markdown-magic-prettier) - Format code blocks with [`prettier`](https://github.com/prettier/prettier)
|
223 | * [engines](https://github.com/camacho/markdown-magic-engines) - Print engines list from `package.json`
|
224 | * [jsdoc](https://github.com/bradtaylorsf/markdown-magic-jsdoc) - Adds jsdoc comment support
|
225 | * [build-badge](https://github.com/rishichawda/markdown-magic-build-badge) - Update branch badges to auto-magically point to current branches.
|
226 | * [package-json](https://github.com/forresst/markdown-magic-package-json) - Add the package.json properties to markdown files
|
227 | * [local-image](https://github.com/stevenbenisek/markdown-magic-local-image)
|
228 | * [figlet](https://github.com/lafourchette/markdown-magic-figlet) - Add FIGfont text to markdown files
|
229 | * [local-image](https://github.com/stevenbenisek/markdown-magic-local-image) - plugin to add local images to markdown
|
230 |
|
231 | ## Adding Custom Transforms
|
232 |
|
233 | Markdown Magic is extendable via plugins.
|
234 |
|
235 | 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.
|
236 |
|
237 | Plugins run in order of registration.
|
238 |
|
239 | The below code is used to generate **this markdown file** via the plugin system.
|
240 |
|
241 |
|
242 |
|
243 | ```js
|
244 | const fs = require('fs')
|
245 | const path = require('path')
|
246 | const markdownMagic = require('../index')
|
247 | // const markdownMagic = require('markdown-magic')
|
248 |
|
249 | const config = {
|
250 | matchWord: 'MD-MAGIC-EXAMPLE', // default matchWord is AUTO-GENERATED-CONTENT
|
251 | transforms: {
|
252 | /* Match <!-- AUTO-GENERATED-CONTENT:START (customTransform:optionOne=hi&optionOne=DUDE) --> */
|
253 | customTransform(content, options) {
|
254 | console.log('original content in comment block', content)
|
255 | console.log('options defined on transform', options)
|
256 | // options = { optionOne: hi, optionOne: DUDE}
|
257 | return `This will replace all the contents of inside the comment ${options.optionOne}`
|
258 | },
|
259 | /* Match <!-- AUTO-GENERATED-CONTENT:START (RENDERDOCS:path=../file.js) --> */
|
260 | RENDERDOCS(content, options) {
|
261 | const fileContents = fs.readFileSync(options.path, 'utf8')
|
262 | const docBlocs = require('doxxx').parseComments(fileContents, { raw: true, skipSingleStar: true })
|
263 | let updatedContent = ''
|
264 | docBlocs.forEach((data) => {
|
265 | updatedContent += `${data.description.full}\n\n`
|
266 | })
|
267 | return updatedContent.replace(/^\s+|\s+$/g, '')
|
268 | },
|
269 | /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
|
270 | pluginExample: require('./plugin-example')({ addNewLine: true }),
|
271 | /* Include plugins from NPM */
|
272 | // count: require('markdown-magic-wordcount'),
|
273 | // github: require('markdown-magic-github-contributors')
|
274 | }
|
275 | }
|
276 |
|
277 | const markdownPath = path.join(__dirname, '..', 'README.md')
|
278 | markdownMagic(markdownPath, config, () => {
|
279 | console.log('Docs ready')
|
280 | })
|
281 | ```
|
282 |
|
283 |
|
284 | ## Plugin Example
|
285 |
|
286 | Plugins must return a transform function with the following signature.
|
287 |
|
288 | ```js
|
289 | return function myCustomTransform (content, options)
|
290 | ```
|
291 |
|
292 |
|
293 |
|
294 | ```js
|
295 | /* Custom Transform Plugin example */
|
296 | const merge = require('deepmerge')
|
297 | module.exports = function customPlugin(pluginOptions) {
|
298 | // set plugin defaults
|
299 | const defaultOptions = {
|
300 | addNewLine: false
|
301 | }
|
302 | const userOptions = pluginOptions || {}
|
303 | const pluginConfig = merge(defaultOptions, userOptions)
|
304 | // return the transform function
|
305 | return function myCustomTransform (content, options) {
|
306 | const newLine = (pluginConfig.addNewLine) ? '\n' : ''
|
307 | const updatedContent = content + newLine
|
308 | return updatedContent
|
309 | }
|
310 | }
|
311 | ```
|
312 |
|
313 |
|
314 | [View the raw file](https://raw.githubusercontent.com/DavidWells/markdown-magic/master/README.md) file and run `npm run docs` to see this plugin run
|
315 |
|
316 | This content is altered by the `pluginExample` plugin registered in `examples/generate-readme.js`
|
317 |
|
318 |
|
319 |
|
320 | ## Other usage examples
|
321 |
|
322 | - [With Github Actions](https://github.com/dineshsonachalam/repo-using-markdown-autodocs)
|
323 | - [Serverless Plugin Repo](https://github.com/serverless/plugins/blob/master/generate-docs.js) this example takes a `json` file and converts it into a github flavored markdown table
|
324 | - [MochaJS](https://github.com/mochajs/mocha/blob/4cc711fa00f7166a2303b77bf2487d1c2cc94621/scripts/markdown-magic.config.js)
|
325 | - [tc39/agendas](https://github.com/tc39/agendas#agendas) - [code](https://github.com/tc39/agendas/blob/65945b1b6658e9829ef95a51bf2632ff44f951e6/scripts/generate.js)
|
326 | - [moleculerjs/moleculer-addons](https://github.com/moleculerjs/moleculer-addons/blob/7cf0f72140717c52621b724cd54a710517106df0/readme-generator.js)
|
327 | - [good-first-issue](https://github.com/bnb/good-first-issue/blob/e65513a1f26167dea3c137008b8796640d8d5303/markdown.config.js)
|
328 | - [navikt/nav-frontend-moduler](https://github.com/navikt/nav-frontend-moduler/blob/20ad521c27a43d3203eab4bc32121e5b8270c077/_scripts/generateReadmes.js)
|
329 | - [country-flags-svg](https://github.com/ronatskiy/country-flags-svg/blob/cfb2368c7e634ebc1679855e13cc3e26ca11187f/markdown.config.js)
|
330 | - [react-typesetting](https://github.com/exogen/react-typesetting/blob/7114cdc8c4cb1b0d59ebc8b5364e808687419889/markdown.config.js)
|
331 | - [and many more!](https://github.com/search?o=desc&p=1&q=markdown-magic+filename%3Apackage.json+-user%3Ah13i32maru+-user%3Aesdoc+-user%3Aes-doc&s=indexed&type=Code)
|
332 |
|
333 | ## Custom Transform Demo
|
334 |
|
335 | 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
|
336 |
|
337 |
|
338 | This will replace all the contents of inside the comment DUDE
|
339 |
|
340 |
|
341 | ## Prior Art
|
342 |
|
343 | This was inspired by [Kent C Dodds](https://twitter.com/kentcdodds) and [jfmengels](https://github.com/jfmengels)'s [all contributors cli](https://github.com/jfmengels/all-contributors-cli) project.
|
344 |
|
345 |
|
346 | This section was generated by the cli config markdown.config.js file
|
347 |
|
348 |
|
349 | ## License
|
350 |
|
351 | [MIT][mit] © [DavidWells][author]
|
352 |
|
353 | [npm-badge]:https://img.shields.io/npm/v/markdown-magic.svg?style=flat-square
|
354 | [npm-link]: http://www.npmjs.com/package/markdown-magic
|
355 | [mit]: http://opensource.org/licenses/MIT
|
356 | [author]: http://github.com/davidwells
|
357 |
|
358 | ## Usage examples
|
359 |
|
360 | - [Project using markdown-magic](https://github.com/search?o=desc&q=filename%3Apackage.json+%22markdown-magic%22&s=indexed&type=Code)
|
361 | - [Examples in md](https://github.com/search?l=Markdown&o=desc&q=AUTO-GENERATED-CONTENT&s=indexed&type=Code)
|