markdown-magic - npm Package Compare versions

Comparing version 0.1.16 to 0.1.17

examples/basic-usage.js

@@ -0,5 +1,5 @@
+import path from 'path'
 import markdownMagic from 'markdown-magic'
-import path from 'path'
 
 const markdownPath = path.join(__dirname, 'README.md')
 markdownMagic(markdownPath)

examples/generate-readme.js

@@ -7,13 +7,15 @@ const fs = require('fs')
 const config = {
+  matchWord: 'MD-MAGIC-EXAMPLE', // default matchWord is AUTO-GENERATED-CONTENT
   transforms: {
-    /* Match AUTO-GENERATED-CONTENT (customTransform:optionOne=hi&optionOne=DUDE) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (customTransform:optionOne=hi&optionOne=DUDE) --> */
     customTransform(content, options) {
-      console.log('original innerContent', content)
-      console.log(options) // { optionOne: hi, optionOne: DUDE}
+      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 (RENDERDOCS:path=../file.js) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (RENDERDOCS:path=../file.js) --> */
     RENDERDOCS(content, options) {
-      const contents = fs.readFileSync(options.path, 'utf8')
-      const docBlocs = require('dox').parseComments(contents, { raw: true, skipSingleStar: true })
+      const fileContents = fs.readFileSync(options.path, 'utf8')
+      const docBlocs = require('dox').parseComments(fileContents, { raw: true, skipSingleStar: true })
       let updatedContent = ''
@@ -25,4 +27,5 @@ docBlocs.forEach((data) => {
     },
-    /* Match AUTO-GENERATED-CONTENT (pluginExample) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
     pluginExample: require('./plugin-example')({ addNewLine: true }),
+    /* Plugins from npm */
     // count: require('markdown-magic-wordcount'),
@@ -38,5 +41,5 @@ // github: require('markdown-magic-github-contributors')
     const mdPath = data.outputFilePath
+    if(!mdPath) return false
     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`
@@ -43,0 +46,0 @@ const gitCommitCommand = `git commit -m '${msg}' --no-verify`

lib/processFile.js

@@ -24,3 +24,3 @@ "use strict" // eslint-disable-line
     /**
-     * `transforms` - *Object* - (optional) Custom commands to transform block contents, see transforms & custom transforms sections below.
+     * - `transforms` - *object* - (optional) Custom commands to transform block contents, see transforms & custom transforms sections below.
      * @type {Object}
@@ -30,3 +30,3 @@ */
     /**
-     * `outputDir` - *String* - (optional) Change output path of new content. Default behavior is replacing the original file
+     * - `outputDir` - *string* - (optional) Change output path of new content. Default behavior is replacing the original file
      * @type {string}
@@ -36,4 +36,4 @@ */
     /**
-     * `matchWord` - *String* - (optional) Comment pattern to look for & replace inner contents. Default `AUTO-GENERATED-CONTENT`
-     * @type {String}
+     * - `matchWord` - *string* - (optional) Comment pattern to look for & replace inner contents. Default `AUTO-GENERATED-CONTENT`
+     * @type {string}
      * @default [AUTO-GENERATED-CONTENT]
@@ -43,3 +43,3 @@ */
     /**
-     * `DEBUG` - *Boolean* - (optional) set debug flag to `true` to inspect the process
+     * - `DEBUG` - *Boolean* - (optional) set debug flag to `true` to inspect the process
      * @type {string}
@@ -46,0 +46,0 @@ */

lib/transforms/index.js

@@ -8,3 +8,3 @@ "use strict" // eslint-disable-line
   /**
-   * ### `CODE`
+   * ### 🔀 CODE
    *
@@ -19,5 +19,5 @@ * Get code from file or URL and put in markdown
    * ```md
-   * <!-- MATCHWORD:START (CODE:src=./relative/path/to/code.js) -->
+   * <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js) -->
    * This content will be dynamically replaced with code from the file
-   * <!-- MATCHWORD:END -->
+   * <!-- AUTO-GENERATED-CONTENT:END -->
    * ```
@@ -34,3 +34,3 @@ *
   /**
-   * ### `REMOTE`
+   * ### 🔀 REMOTE
    *
@@ -44,5 +44,5 @@ * Get any remote Data and put in markdown
    * ```md
-   * <!-- MATCHWORD:START (REMOTE:url=http://url-to-raw-md.md) -->
+   * <!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=http://url-to-raw-md-file.md) -->
    * This content will be dynamically replace from the remote url
-   * <!-- MATCHWORD:END -->
+   * <!-- AUTO-GENERATED-CONTENT:END -->
    * ```
@@ -59,3 +59,3 @@ *
   /**
-   * ### `TOC`
+   * ### 🔀 TOC
    *
@@ -65,4 +65,4 @@ * 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`
+   * - `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
@@ -73,5 +73,5 @@ * - `excludeText` - *string* - (optional): Text to exclude in the table of contents. Default `Table of Contents`
    * ```md
-   * <!-- MATCHWORD:START (TOC) -->
+   * <!-- AUTO-GENERATED-CONTENT:START (TOC) -->
    * toc will be generated here
-   * <!-- MATCHWORD:END -->
+   * <!-- AUTO-GENERATED-CONTENT:END -->
    * ```
@@ -78,0 +78,0 @@ *

markdown.config.js

@@ -1,8 +0,5 @@
-/**
- * CLI config example
- * markdown.config.js as default name
- */
+/* CLI config file example */
 module.exports = {
   transforms: {
-    /* Match AUTO-GENERATED-CONTENT (LOLZ) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (LOLZ) --> */
     LOLZ(content, options) {
@@ -9,0 +6,0 @@ return `This section was generated by the cli config markdown.config.js file`

package.json

 {
   "name": "markdown-magic",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "Automatically update markdown files with content from external sources",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -20,3 +20,3 @@ # Markdown Magic
 ## Table of Contents
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (TOC:collapse=true&collapseText=Click to expand) -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (TOC:collapse=true&collapseText=Click to expand) -->
 <details>
@@ -32,7 +32,7 @@ <summary>Click to expand</summary>
 - [Transforms](#transforms)
-  * [`CODE`](#code)
-  * [`REMOTE`](#remote)
-  * [`TOC`](#toc)
-- [Plugins](#plugins)
-- [Custom Transforms](#custom-transforms)
+  * [🔀 CODE](#%F0%9F%94%80-code)
+  * [🔀 REMOTE](#%F0%9F%94%80-remote)
+  * [🔀 TOC](#%F0%9F%94%80-toc)
+- [🔌 Third Party Transforms a.k.a. Plugins](#%F0%9F%94%8C-third-party-transforms-aka-plugins)
+- [Adding Custom Transforms](#adding-custom-transforms)
 - [Plugin Example](#plugin-example)
@@ -44,3 +44,3 @@ - [Other usage examples](#other-usage-examples)
 </details>
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END -->
 
@@ -54,7 +54,7 @@ ## Install
 ## Usage
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (CODE:src=./examples/basic-usage.js&order=last) -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./examples/basic-usage.js) -->
 <!-- The below code snippet is automatically added from ./examples/basic-usage.js -->
 ```js
+import path from 'path'
 import markdownMagic from 'markdown-magic'
-import path from 'path'
 
@@ -64,9 +64,9 @@ const markdownPath = path.join(__dirname, 'README.md')
 ```
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END *-->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END *-->
 
 ## CLI Usage
 
-You can use markdown-magic as a CLI command. This is useful for adding the package quickly to your `package.json` npm scripts
+You can use `markdown-magic` as a CLI command. Run `markdown --help` to see all available CLI options
 
-```
+```bash
 markdown --help
@@ -77,19 +77,27 @@ # or
 
-Run `markdown --help` to see all available CLI options
+This is useful for adding the package quickly to your `package.json` npm scripts
 
 CLI usage example with options
+
+```bash
+md-magic --path '**/*.md' --config ./config.file.js
 ```
-markdown --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.
+
+```json
+"scripts": {
+  "docs": "md-magic --path '**/*.md' --ignore 'node_modules'"
+},
 ```
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (CODE:src=./markdown.config.js) -->
+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.
+
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./markdown.config.js) -->
 <!-- The below code snippet is automatically added from ./markdown.config.js -->
 ```js
-/**
- * CLI config example
- * markdown.config.js as default name
- */
+/* CLI config file example */
 module.exports = {
   transforms: {
-    /* Match AUTO-GENERATED-CONTENT (LOLZ) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (LOLZ) --> */
     LOLZ(content, options) {
@@ -104,5 +112,5 @@ return `This section was generated by the cli config markdown.config.js file`
 ```
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END *-->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END *-->
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (RENDERDOCS:path=./index.js)
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (RENDERDOCS:path=./index.js)
 - Do not remove or modify this section -->
@@ -116,16 +124,16 @@ ### API
 - `callback` - callback to run after markdown updates
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END - Do not remove or modify this section -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (RENDERDOCS:path=./lib/processFile.js)
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (RENDERDOCS:path=./lib/processFile.js)
 - Do not remove or modify this section -->
 ### Configuration Options
 
-`transforms` - *Object* - (optional) Custom commands to transform block contents, see transforms & custom transforms sections below.
+- `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
+- `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`
+- `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
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END - Do not remove or modify this section -->
+- `DEBUG` - *Boolean* - (optional) set debug flag to `true` to inspect the process
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
@@ -137,4 +145,4 @@
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (RENDERDOCS:path=./lib/transforms/index.js) - Do not remove or modify this section -->
-### `CODE`
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (RENDERDOCS:path=./lib/transforms/index.js) - Do not remove or modify this section -->
+### 🔀 CODE
 
@@ -149,5 +157,5 @@ Get code from file or URL and put in markdown
 ```md
-<!-- MATCHWORD:START (CODE:src=./relative/path/to/code.js) -->
+<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js) -->
 This content will be dynamically replaced with code from the file
-<!-- MATCHWORD:END -->
+<!-- AUTO-GENERATED-CONTENT:END -->
 ```
@@ -159,3 +167,3 @@
 
-### `REMOTE`
+### 🔀 REMOTE
 
@@ -169,5 +177,5 @@ Get any remote Data and put in markdown
 ```md
-<!-- MATCHWORD:START (REMOTE:url=http://url-to-raw-md.md) -->
+<!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=http://url-to-raw-md-file.md) -->
 This content will be dynamically replace from the remote url
-<!-- MATCHWORD:END -->
+<!-- AUTO-GENERATED-CONTENT:END -->
 ```
@@ -179,3 +187,3 @@
 
-### `TOC`
+### 🔀 TOC
 
@@ -185,4 +193,4 @@ 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`
+- `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
@@ -193,5 +201,5 @@ - `excludeText` - *string* - (optional): Text to exclude in the table of contents. Default `Table of Contents`
 ```md
-<!-- MATCHWORD:START (TOC) -->
+<!-- AUTO-GENERATED-CONTENT:START (TOC) -->
 toc will be generated here
-<!-- MATCHWORD:END -->
+<!-- AUTO-GENERATED-CONTENT:END -->
 ```
@@ -202,5 +210,5 @@
 ---
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END - Do not remove or modify this section -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
-## Plugins
+## 🔌 Third Party Transforms a.k.a. Plugins
 
@@ -215,7 +223,7 @@ * [wordcount](https://github.com/DavidWells/markdown-magic-wordcount/) - Add wordcount to markdown files
 
-## Custom Transforms
+## Adding 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`.
+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.
 
@@ -226,3 +234,3 @@ Plugins run in order of registration.
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (CODE:src=./examples/generate-readme.js) -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./examples/generate-readme.js) -->
 <!-- The below code snippet is automatically added from ./examples/generate-readme.js -->
@@ -236,13 +244,15 @@ ```js
 const config = {
+  matchWord: 'MD-MAGIC-EXAMPLE', // default matchWord is AUTO-GENERATED-CONTENT
   transforms: {
-    /* Match AUTO-GENERATED-CONTENT (customTransform:optionOne=hi&optionOne=DUDE) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (customTransform:optionOne=hi&optionOne=DUDE) --> */
     customTransform(content, options) {
-      console.log('original innerContent', content)
-      console.log(options) // { optionOne: hi, optionOne: DUDE}
+      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 (RENDERDOCS:path=../file.js) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (RENDERDOCS:path=../file.js) --> */
     RENDERDOCS(content, options) {
-      const contents = fs.readFileSync(options.path, 'utf8')
-      const docBlocs = require('dox').parseComments(contents, { raw: true, skipSingleStar: true })
+      const fileContents = fs.readFileSync(options.path, 'utf8')
+      const docBlocs = require('dox').parseComments(fileContents, { raw: true, skipSingleStar: true })
       let updatedContent = ''
@@ -254,4 +264,5 @@ docBlocs.forEach((data) => {
     },
-    /* Match AUTO-GENERATED-CONTENT (pluginExample) */
+    /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
     pluginExample: require('./plugin-example')({ addNewLine: true }),
+    /* Plugins from npm */
     // count: require('markdown-magic-wordcount'),
@@ -267,5 +278,5 @@ // github: require('markdown-magic-github-contributors')
     const mdPath = data.outputFilePath
+    if(!mdPath) return false
     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`
@@ -284,3 +295,3 @@ const gitCommitCommand = `git commit -m '${msg}' --no-verify`
 ```
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END -->
 
@@ -295,3 +306,3 @@ ## Plugin Example
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (CODE:src=./examples/plugin-example.js) -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./examples/plugin-example.js) -->
 <!-- The below code snippet is automatically added from ./examples/plugin-example.js -->
@@ -316,9 +327,9 @@ ```js
 ```
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END -->
 
 [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
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (pluginExample) DO not edit ⛔️ -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (pluginExample) DO not edit ⛔️ -->
 This content is altered by the `pluginExample` plugin registered in `examples/generate-readme.js`
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END -->
 
@@ -333,5 +344,5 @@ ## Other usage examples
 
-<!-- ⛔️ AUTO-GENERATED-CONTENT:START (customTransform:optionOne=hi&optionOne=DUDE) - Do not remove or modify this section -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (customTransform:optionOne=hi&optionOne=DUDE) - Do not remove or modify this section -->
 This will replace all the contents of inside the comment DUDE
-<!-- ⛔️ AUTO-GENERATED-CONTENT:END - Do not remove or modify this section -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
@@ -342,4 +353,4 @@ ## Prior Art
 
-<!-- AUTO-GENERATED-CONTENT:START (LOLZ)-->
+<!-- MD-MAGIC-EXAMPLE:START (LOLZ)-->
 This section was generated by the cli config markdown.config.js file
-<!-- AUTO-GENERATED-CONTENT:END (LOLZ)-->
+<!-- MD-MAGIC-EXAMPLE:END (LOLZ)-->

No alert changes

Improved metrics

Total package byte prevSize

52432

increased by2.08%

Number of lines in readme file

331

increased by3.44%

No dependency changes