markdown-magic 3.0.3 → 3.0.4

package/README.md

@@ -19,135 +19,250 @@ This `README.md` is generated with `markdown-magic` [view the raw file](https://
 [Video demo](http://www.youtube.com/watch?v=4V2utrvxwJ8) • [Example Repo](https://github.com/DavidWells/repo-using-markdown-magic)
 
 ## Table of Contents
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (TOC:collapse=true&collapseText=Click to expand) -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START TOC collapse=true collapseText="Click to expand" -->
 <details>
 <summary>Click to expand</summary>
 
 - [About](#about)
 - [Install](#install)
 - [Usage](#usage)
+  - [Running via CLI](#running-via-cli)
+  - [Running programmatically](#running-programmatically)
+- [Syntax Examples](#syntax-examples)
+  - [Basic](#basic)
+  - [Curly braces](#curly-braces)
+  - [Square brackets](#square-brackets)
+  - [Parentheses](#parentheses)
+  - [Functions](#functions)
   - [API](#api)
-  - [Configuration Options](#configuration-options)
-- [CLI Usage](#cli-usage)
+    - [`MarkdownMagicOptions`](#markdownmagicoptions)
+    - [`OutputConfig`](#outputconfig)
+    - [`MarkdownMagicResult`](#markdownmagicresult)
 - [Transforms](#transforms)
   - [> TOC](#-toc)
   - [> CODE](#-code)
   - [> FILE](#-file)
   - [> REMOTE](#-remote)
 - [Inline transforms](#inline-transforms)
-- [🔌 Markdown magic plugins](#-markdown-magic-plugins)
+- [Legacy v1 & v2 plugins](#legacy-v1--v2-plugins)
 - [Adding Custom Transforms](#adding-custom-transforms)
 - [Plugin Example](#plugin-example)
 - [Other usage examples](#other-usage-examples)
 - [Custom Transform Demo](#custom-transform-demo)
-- [Prior Art](#prior-art)
-- [License](#license)
 - [Usage examples](#usage-examples)
 - [Misc Markdown helpers](#misc-markdown-helpers)
+- [Prior Art](#prior-art)
+- [License](#license)
 
 </details>
 <!-- ⛔️ MD-MAGIC-EXAMPLE:END -->
 
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START FILE src=./docs/1_Getting-Started.md -->
 ## Install
 
+To get started. Install the npm package.
+
 ```bash
 npm install markdown-magic --save-dev
 ```
 
 ## Usage
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./examples/1-_basic-usage.js) -->
-<!-- The below code snippet is automatically added from ./examples/1-_basic-usage.js -->
+
+Use comment blocks in your markdown
+
+**Example:**
+```md
+<!-- doc-gen remote url=http://url-to-raw-md-file.md -->
+This content will be dynamically replaced from the remote url
+<!-- end-doc-gen -->
+```
+
+Then run `markdown-magic` via it's CLI or programmatically.
+
+### Running via CLI
+
+Run `markdown --help` to see all available CLI options
+
+```bash
+markdown
+# or
+md-magic
+```
+
+CLI usage example with options
+
+```bash
+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.
+
+```json
+"scripts": {
+  "docs": "md-magic --path '**/*.md'"
+},
+```
+
+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.
+
+### Running programmatically
+
+```js
+const { markdownMagic } = require('../lib')
+
+/* By default all .md files in cwd will be processed */
+markdownMagic().then((results) => {
+  console.log('result keys', Object.keys(results))
+})
+```
+
 ```js
 import path from 'path'
 import markdownMagic from 'markdown-magic'
 
+// Process a Single File
 const markdownPath = path.join(__dirname, 'README.md')
 markdownMagic(markdownPath)
 ```
 <!-- ⛔️ MD-MAGIC-EXAMPLE:END *-->
 
-### API
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START (FILE:src=./docs/Syntax.md) -->
+## Syntax Examples
 
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (RENDERDOCS:path=./lib/index.js)
-- Do not remove or modify this section -->
-Markdown Magic
-<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
+There are various syntax options. Choose your favorite.
 
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (RENDERDOCS:path=./lib/process-file.js)
-- Do not remove or modify this section -->
-### Configuration Options
+### Basic
 
-- `transforms` - *object* - (optional) Custom commands to transform block contents, see transforms & custom transforms sections below.
+`openWord transformName [opts]`
 
-- `outputDir` - *string* - (optional) Change output path of new content. Default behavior is replacing the original file
+```md
+<!-- doc-gen transformName optionOne='hello' optionTwo='there' -->
+content to be replaced
+<!-- end-doc-gen -->
+```
 
-- `matchWord` - *string* - (optional) Comment pattern to look for & replace inner contents. Default `AUTO-GENERATED-CONTENT`
+### Curly braces
 
-- `DEBUG` - *Boolean* - (optional) set debug flag to `true` to inspect the process
-<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
+`openWord {transformName} [opts]`
 
-## CLI Usage
+```md
+<!-- doc-gen {transformName} optionOne='hello' optionTwo='there' -->
+content to be replaced
+<!-- end-doc-gen -->
+```
 
-You can use `markdown-magic` as a CLI command. Run `markdown --help` to see all available CLI options
+### Square brackets
 
-```bash
-markdown --help
-# or
-md-magic
+`openWord [transformName] [opts]`
+
+```md
+<!-- doc-gen [transformName] optionOne='hello' optionTwo='there' -->
+content to be replaced
+<!-- end-doc-gen -->
 ```
 
-This is useful for adding the package quickly to your `package.json` npm scripts
+### Parentheses
 
-CLI usage example with options
+`openWord (transformName) [opts]`
 
-```bash
-md-magic --path '**/*.md' --config ./config.file.js
+```md
+<!-- doc-gen (transformName) optionOne='hello' optionTwo='there' -->
+content to be replaced
+<!-- end-doc-gen -->
 ```
 
-In NPM scripts, `npm run docs` would run the markdown magic and parse all the `.md` files in the directory.
+### Functions
 
-```json
-"scripts": {
-  "docs": "md-magic --path '**/*.md' --ignore 'node_modules'"
-},
+`openWord transformName([opts])`
+
+```md
+<!-- doc-gen transformName(
+  foo='bar'
+  baz=['qux', 'quux']
+) -->
+content to be replaced
+<!-- end-doc-gen -->
 ```
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END *-->
 
-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 JSDocs path="./lib/index.js" -->
+### API
+
+Markdown Magic Instance
 
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./md.config.js) -->
-<!-- The below code snippet is automatically added from ./md.config.js -->
 ```js
-/* CLI markdown.config.js file example */
-module.exports = {
-  // handleOutputPath: (currentPath) => {
-  //   const newPath =  'x' + currentPath
-  //   return newPath
-  // },
-  // handleOutputPath: (currentPath) => {
-  //   const newPath = currentPath.replace(/fixtures/, 'fixtures-out')
-  //   return newPath
-  // },
-  transforms: {
-    /* Match <!-- AUTO-GENERATED-CONTENT:START (transformOne) --> */
-    transformOne() {
-      return `This section was generated by the cli config md.config.js file`
-    },
-    functionName() {
-      return `xyz`
-    }
-  }
-}
+markdownMagic(globOrOpts, options)
 ```
-<!-- ⛔️ MD-MAGIC-EXAMPLE:END *-->
+
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `globOrOpts` | `FilePathsOrGlobs or MarkdownMagicOptions` | Files to process or config. |
+| `options` (optional) | `MarkdownMagicOptions` | Markdown magic config. |
+
+**Returns**
+
+`Promise<MarkdownMagicResult>`
+
+**Example**
+
+```js
+markdownMagic(['**.**.md'], options).then((result) => {
+  console.log(`Processing complete`, result)
+})
+```
+
+#### `MarkdownMagicOptions`
+
+Configuration for markdown magic
+
+Below is the main config for `markdown-magic`
+
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `files` (optional) | `FilePathsOrGlobs` | Files to process. |
+| `transforms` (optional) | `Array` | Custom commands to transform block contents, see transforms & custom transforms sections below. Default: `defaultTransforms` |
+| `output` (optional) | `OutputConfig` | Output configuration. |
+| `syntax` (optional) | `SyntaxType` | Syntax to parse. Default: `md` |
+| `open` (optional) | `string` | Opening match word. Default: `doc-gen` |
+| `close` (optional) | `string` | Closing match word. If not defined will be same as opening word. Default: `end-doc-gen` |
+| `cwd` (optional) | `string` | Current working directory. Default process.cwd(). Default: `process.cwd() ` |
+| `outputFlatten` (optional) | `boolean` | Flatten files that are output. |
+| `useGitGlob` (optional) | `boolean` | Use git glob for LARGE file directories. |
+| `dryRun` (optional) | `boolean` | See planned execution of matched blocks. Default: `false` |
+| `debug` (optional) | `boolean` | See debug details. Default: `false` |
+| `silent` (optional) | `boolean` | Silence all console output. Default: `false` |
+| `failOnMissingTransforms` (optional) | `boolean` | Fail if transform functions are missing. Default skip blocks. Default: `false` |
+
+#### `OutputConfig`
+
+Optional output configuration
+
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `directory` (optional) | `string` | Change output path of new content. Default behavior is replacing the original file. |
+| `removeComments` (optional) | `boolean` | Remove comments from output. Default is false. Default: `false` |
+| `pathFormatter` (optional) | `function` | Custom function for altering output paths. |
+| `applyTransformsToSource` (optional) | `boolean` | Apply transforms to source file. Default is true. This is for when outputDir is set. Default: `false` |
+
+#### `MarkdownMagicResult`
+
+Result of markdown processing
+
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `errors` | `Array` | Any errors encountered. |
+| `filesChanged` | `Array<string>` | Modified files. |
+| `results` | `Array` | md data. |
+<!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
 ## 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.
 
-<!-- ⛔️ MD-MAGIC-EXAMPLE:START (RENDERDOCS:path=./lib/transforms/index.js) - Do not remove or modify this section -->
+<!-- ⛔️ MD-MAGIC-EXAMPLE:START JSDocs path="./lib/transforms/index.js" -->
 ### > TOC
 
-Generate taxxxxble of contents from markdown file
+Generate table of contents from markdown file
 
 **Options:**
 - `firsth1` - *boolean* - (optional): Show first h1 of doc in table of contents. Default `false`
@@ -158,15 +273,20 @@ Generate taxxxxble of contents from markdown file
 
 **Example:**
 ```md
-<!-- AUTO-GENERATED-CONTENT:START (TOC) -->
+<!-- doc-gen (TOC) -->
 toc will be generated here
-<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- end-doc-gen -->
 ```
 
 Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
 
 ---
 
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `content` | `string` | The current content of the comment block. |
+| `options` | `object` | The options passed in from the comment declaration. |
+
 ### > CODE
 
 Get code from file or URL and put in markdown
@@ -179,21 +299,26 @@ Get code from file or URL and put in markdown
 
 **Example:**
 ```md
-<!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js) -->
+<!-- doc-gen (CODE:src=./relative/path/to/code.js) -->
 This content will be dynamically replaced with code from the file
-<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- end-doc-gen -->
 ```
 
 ```md
- <!-- AUTO-GENERATED-CONTENT:START (CODE:src=./relative/path/to/code.js&lines=22-44) -->
+ <!-- doc-gen (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 -->
+ <!-- end-doc-gen -->
  ```
 
 Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
 
 ---
 
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `content` | `string` | The current content of the comment block. |
+| `options` | `object` | The options passed in from the comment declaration. |
+
 ### > FILE
 
 Get local file contents.
@@ -203,15 +328,20 @@ Get local file contents.
 
 **Example:**
 ```md
-<!-- AUTO-GENERATED-CONTENT:START (FILE:src=./path/to/file) -->
+<!-- doc-gen (FILE:src=./path/to/file) -->
 This content will be dynamically replaced from the local file
-<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- end-doc-gen -->
 ```
 
 Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
 
 ---
 
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `content` | `string` | The current content of the comment block. |
+| `options` | `object` | The options passed in from the comment declaration. |
+
 ### > REMOTE
 
 Get any remote Data and put in markdown
@@ -221,14 +351,19 @@ Get any remote Data and put in markdown
 
 **Example:**
 ```md
-<!-- AUTO-GENERATED-CONTENT:START (REMOTE:url=http://url-to-raw-md-file.md) -->
+<!-- doc-gen (REMOTE:url=http://url-to-raw-md-file.md) -->
 This content will be dynamically replaced from the remote url
-<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- end-doc-gen -->
 ```
 
 Default `MATCHWORD` is `AUTO-GENERATED-CONTENT`
 
 ---
+
+| Name | Type | Description |
+|:---------------------------|:---------------:|:-----------|
+| `content` | `string` | The current content of the comment block. |
+| `options` | `object` | The options passed in from the comment declaration. |
 <!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
 ## Inline transforms
@@ -239,10 +374,12 @@ The face symbol 👉 <!-- MD-MAGIC-EXAMPLE:START (INLINE_EXAMPLE) -->**⊂◉‿
 
 **Example:**
 ```md
-<!-- AUTO-GENERATED-CONTENT:START (FILE:src=./path/to/file) -->xyz<!-- AUTO-GENERATED-CONTENT:END -->
+<!-- doc-gen (FILE:src=./path/to/file) -->xyz<!-- end-doc-gen -->
 ```
 
-## 🔌 Markdown magic plugins
+## Legacy v1 & v2 plugins
+
+These plugins work with older versions of markdown-magic. Adapting them to the newer plugin syntax should be pretty straight forward.
 
 * [wordcount](https://github.com/DavidWells/markdown-magic-wordcount/) - Add wordcount to markdown files
 * [github-contributors](https://github.com/DavidWells/markdown-magic-github-contributors) - List out the contributors of a given repository
@@ -273,13 +410,12 @@ Plugins run in order of registration.
 The below code is used to generate **this markdown file** via the plugin system.
 
 <!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./examples/generate-readme.js) -->
-<!-- The below code snippet is automatically added from ./examples/generate-readme.js -->
 ```js
-const fs = require('fs')
 const path = require('path')
-const doxxx = require('doxxx')
+const { readFileSync } = require('fs')
+const { parseComments } = require('doxxx')
 const { markdownMagic } = require('../lib')
-// const { markdownMagic } = require('markdown-magic')
+const { deepLog } = require('../lib/utils/logs')
 
 const config = {
   matchWord: 'MD-MAGIC-EXAMPLE', // default matchWord is AUTO-GENERATED-CONTENT
@@ -291,21 +427,81 @@ const config = {
       // 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(api) {
-      console.log('api', api)
-      const { options } = api
-      console.log('options.path', path.resolve(options.path))
-      const fileContents = fs.readFileSync(options.path, 'utf8')
-      const docBlocs = doxxx.parseComments(fileContents, { raw: true, skipSingleStar: true })
+    /* Match <!-- AUTO-GENERATED-CONTENT:START JSDocs path="../file.js" --> */
+    JSDocs(markdownMagicPluginAPI) {
+      const { options } = markdownMagicPluginAPI
+      const fileContents = readFileSync(options.path, 'utf8')
+      const docBlocs = parseComments(fileContents, { skipSingleStar: true })
+        .filter((item) => {
+          return !item.isIgnored
+        })
+        /* Remove empty comments with no tags */
         .filter((item) => {
           return item.tags.length
         })
-      console.log('docBlocs', docBlocs)
-      // process.exit(1)
+        /* Remove inline type defs */
+        .filter((item) => {
+          return item.description.text !== ''
+        })
+        /* Sort types to end */
+        .sort((a, b) => {
+          if (a.type && !b.type) return 1
+          if (!a.type && b.type) return -1
+          return 0
+        })
+
+      docBlocs.forEach((data) => {
+        // console.log('data', data)
+        delete data.code
+      })
+      // console.log('docBlocs', docBlocs)
+
+      if (docBlocs.length === 0) {
+        throw new Error('No docBlocs found')
+      }
+
+      // console.log(docBlocs.length)
       let updatedContent = ''
       docBlocs.forEach((data) => {
-        updatedContent += `${data.description.full}\n\n`
+        if (data.type) {
+          updatedContent += `#### \`${data.type}\`\n\n`
+        }
+
+        updatedContent += `${data.description.text}\n`
+
+        if (data.tags.length) {
+         let table =  '| Name | Type | Description |\n'
+          table += '|:---------------------------|:---------------:|:-----------|\n'
+          data.tags.filter((tag) => {
+            if (tag.tagType === 'param') return true
+            if (tag.tagType === 'property') return true
+            return false
+          }).forEach((tag) => {
+            const optionalText = tag.isOptional ? ' (optional) ' : ' '
+            const defaultValueText = (typeof tag.defaultValue !== 'undefined') ? ` Default: \`${tag.defaultValue}\` ` : ' '
+            console.log('tag', tag)
+            table += `| \`${tag.name}\`${optionalText}`
+            table += `| \`${tag.type.replace('|', 'or')}\` `
+            table += `| ${tag.description.replace(/\.\s?$/, '')}.${defaultValueText}|\n`
+          })
+          updatedContent+= `\n${table}\n`
+
+          const returnValues = data.tags.filter((tag) => tag.tagType === 'returns')
+          if (returnValues.length) {
+            returnValues.forEach((returnValue) => {
+              updatedContent += `**Returns**\n\n`
+              updatedContent += `\`${returnValue.type}\`\n\n`
+            })
+          }
+
+          const examples = data.tags.filter((tag) => tag.tagType === 'example')
+          if (examples.length) {
+            examples.forEach((example) => {
+              updatedContent += `**Example**\n\n`
+              updatedContent += `\`\`\`js\n${example.tagValue}\n\`\`\`\n\n`
+            })
+          }
+        }
       })
       return updatedContent.replace(/^\s+|\s+$/g, '')
     },
@@ -313,7 +509,6 @@ const config = {
       return '**⊂◉‿◉つ**'
     },
     lolz() {
-      console.log('run lol')
       return `This section was generated by the cli config markdown.config.js file`
     },
     /* Match <!-- AUTO-GENERATED-CONTENT:START (pluginExample) --> */
@@ -340,7 +535,6 @@ return function myCustomTransform (content, options)
 ```
 
 <!-- ⛔️ MD-MAGIC-EXAMPLE:START (CODE:src=./examples/plugin-example.js) -->
-<!-- The below code snippet is automatically added from ./examples/plugin-example.js -->
 ```js
 /* Custom Transform Plugin example */
 module.exports = function customPlugin(pluginOptions) {
@@ -386,6 +580,16 @@ View the raw source of this `README.md` file to see the comment block and see ho
 This will replace all the contents of inside the comment DUDE
 <!-- ⛔️ MD-MAGIC-EXAMPLE:END - Do not remove or modify this section -->
 
+## Usage examples
+
+- [Project using markdown-magic](https://github.com/search?o=desc&q=filename%3Apackage.json+%22markdown-magic%22&s=indexed&type=Code)
+- [Examples in md](https://github.com/search?l=Markdown&o=desc&q=AUTO-GENERATED-CONTENT&s=indexed&type=Code)
+
+
+## Misc Markdown helpers
+
+- https://github.com/azu/markdown-function
+
 ## Prior Art
 
 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.
@@ -397,14 +601,4 @@ This was inspired by [Kent C Dodds](https://twitter.com/kentcdodds) and [jfmenge
 [npm-badge]:https://img.shields.io/npm/v/markdown-magic.svg?style=flat-square
 [npm-link]: http://www.npmjs.com/package/markdown-magic
 [mit]:      http://opensource.org/licenses/MIT
-[author]:   http://github.com/davidwells
-
-## Usage examples
-
-- [Project using markdown-magic](https://github.com/search?o=desc&q=filename%3Apackage.json+%22markdown-magic%22&s=indexed&type=Code)
-- [Examples in md](https://github.com/search?l=Markdown&o=desc&q=AUTO-GENERATED-CONTENT&s=indexed&type=Code)
-
-
-## Misc Markdown helpers
-
-- https://github.com/azu/markdown-function
+[author]:   http://github.com/davidwells

package/cli.js

@@ -3,5 +3,8 @@ const { runCli } = require('./lib/cli')
 const argv = process.argv.slice(2)
 const cliArgs = mri(argv)
 
+/*
+console.log('Raw args:', argv)
+console.log('Before args:', cliArgs)
+/** */
 runCli(cliArgs)
-