From f6bb586435418ef954f77ddfee18d4cb0c0b4781 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Wed, 10 Jun 2020 18:41:27 +0200
Subject: [PATCH] feat: rehype plugins (#65)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat: handle rehype plugins with recursive merging

BREAKING CHANGE: plugins disappear in favor of remarkPlugins and rehypePlugins. basePlugins also disappear in favor of deep merging and functions override

* docs: update for rehype plugins

* feat(lib): improve plugins parser

* docs: fix code-group component

* docs: update for new plugins options

* docs: add changelog page

* feat(lib): use nuxt resolver for local plugins

* docs: update configuration

* feat(lib): remove nuxt dependency

* docs: minor improvements

* chore: add getOptions for programmatic usage

* fix(lib): add missing property after merge

* chore(lib): improve plugins parsing

* test: options merging

Co-authored-by: Sébastien Chopin <seb@nuxtjs.com>
---
 docs/components/bases/CodeGroup.vue |  10 +-
 docs/content/en/advanced.md         |   2 +-
 docs/content/en/changelog.md        |  21 ++++
 docs/content/en/configuration.md    | 156 ++++++++++++++++++++++------
 docs/content/en/writing.md          |   8 +-
 lib/index.js                        |  59 ++++-------
 lib/parsers/markdown/index.js       |  32 ++----
 lib/utils.js                        |  90 ++++++++++++++++
 test/options.test.js                | 143 +++++++++++++++++++++++++
 9 files changed, 423 insertions(+), 98 deletions(-)
 create mode 100644 docs/content/en/changelog.md
 create mode 100644 lib/utils.js
 create mode 100644 test/options.test.js

diff --git a/docs/components/bases/CodeGroup.vue b/docs/components/bases/CodeGroup.vue
index 4ae285a35..3ed036c5a 100644
--- a/docs/components/bases/CodeGroup.vue
+++ b/docs/components/bases/CodeGroup.vue
@@ -1,6 +1,6 @@
 <template>
   <div class="code-group">
-    <div class="rounded-t border-b-2 border-gray-700 px-2 bg-gray-800 text-sm text-white relative ">
+    <div class="rounded-t border-b-2 border-gray-700 px-2 bg-gray-800 text-sm text-white relative">
       <button
         v-for="({ label }, i) in tabs"
         ref="tabs"
@@ -8,9 +8,7 @@
         class="px-4 py-3 text-gray-400 font-bold font-mono"
         :class="[activeTabIndex === i && 'active']"
         @click="updateTabs(i)"
-      >
-        {{ label }}
-      </button>
+      >{{ label }}</button>
       <span ref="highlight-underline" class="highlight-underline" />
     </div>
     <slot />
@@ -31,7 +29,7 @@ export default {
     }
   },
   created () {
-    this.$slots.default.map((slot) => {
+    this.$slots.default.filter(slot => Boolean(slot.componentOptions)).map((slot) => {
       this.tabs.push({
         label: slot.componentOptions.propsData.label,
         elm: null
@@ -40,7 +38,7 @@ export default {
     this.activeTabIndex = 0
   },
   mounted () {
-    this.tabs = this.$slots.default.map((slot) => {
+    this.tabs = this.$slots.default.filter(slot => Boolean(slot.componentOptions)).map((slot) => {
       return {
         label: slot.componentOptions.propsData.label,
         elm: slot.elm
diff --git a/docs/content/en/advanced.md b/docs/content/en/advanced.md
index 9f864d13a..341c9277d 100644
--- a/docs/content/en/advanced.md
+++ b/docs/content/en/advanced.md
@@ -17,7 +17,7 @@ category: Getting started
 
 ```js
 export default {
-  modules: [,
+  modules: [
     '@nuxt/content'
   ],
   generate: {
diff --git a/docs/content/en/changelog.md b/docs/content/en/changelog.md
new file mode 100644
index 000000000..033d7ab50
--- /dev/null
+++ b/docs/content/en/changelog.md
@@ -0,0 +1,21 @@
+---
+title: Changelog
+description: 'Learn the changes made of the different versions of @nuxt/content module.'
+position: 8
+category: Getting started
+---
+
+## v2.0.0
+
+### Markdown plugins
+
+<base-alert>
+  markdown.basePlugins and markdown.plugins have been removed in favor of markdown.remarkPlugins and markdown.rehypePlugins.
+</base-alert>
+
+- Overriding plugins options can still be done but with prefixing by `remark` or `rehype`, for examps `externalLinks` becomes `remarkExternalLinks`.
+- You can now override all plugins or append a new plugin using `remarkPlugins` / `rehypePlugins`.
+- You can use local plugins using `~/plugins/remark-plugin.js`.
+- You can register and configure plugins on the same line like `['remark-plugin', { option: 1 }]`.
+
+Everything is documented in [this section](/configuration#markdown).
\ No newline at end of file
diff --git a/docs/content/en/configuration.md b/docs/content/en/configuration.md
index 59f4ee153..b6b906b08 100644
--- a/docs/content/en/configuration.md
+++ b/docs/content/en/configuration.md
@@ -15,7 +15,16 @@ export default {
 }
 ```
 
-See [defaults options](#defaults).
+Before diving into the individual attributes, please have a look [at the default settings](#defaults) of the module.
+
+### Merging defaults
+
+You can define every option either as function or as static value (primitives, objects, arrays, ...).
+if you use a function, the default value will be provided as the first argument.
+
+If you *don't* use a function to define you properties, the module will try to
+merge them with the default values. This can be handy for `markdown.remarkPlugins`, `markdown.rehypePlugins` and so on because
+the defaults are quite sensible. If you don't want to have the defaults include, just use a function.
 
 ## Properties
 
@@ -79,46 +88,128 @@ content: {
 
 ### `markdown`
 
-This module uses [remark](https://github.com/remarkjs/remark) under the hood to compile markdown files into JSON AST that will be stored into the `body` variable.
+This module uses [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) under the hood to compile markdown files into JSON AST that will be stored into the `body` variable.
 
-By default, this module uses plugins to improve markdown parsing. You can add your own by using `plugins` or override the default ones by using `basePlugins`. Each plugin is configured using its name in camelCase: `remark-external-links` => `externalLinks`.
+<base-alert type="info">
+The following explanation is valid for both `remarkPlugins` and `rehypePlugins`
+</base-alert>
 
-> You check for remark plugins [here](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-plugins)
+To configure how the module will parse Markdown, you can:
 
-### `markdown.basePlugins`
+- Add a new plugin to the defaults:
 
-- Type: `Array`
-- Default: `['remark-squeeze-paragraphs', 'remark-slug', 'remark-autolink-headings', 'remark-external-links', 'remark-footnotes']`
+```js{}[nuxt.config.js]
+export default {
+  content: {
+    markdown: {
+      remarkPlugins: ['remark-emoji']
+    }
+  }
+}
+```
 
-### `markdown.plugins`
+- Override the default plugins:
 
-- Type: `Array`
-- Default: `[]`
+```js{}[nuxt.config.js]
+export default {
+  content: {
+    markdown: {
+      remarkPlugins: () => ['remark-emoji']
+    }
+  }
+}
+```
 
-### `markdown.externalLinks`
+- Use local plugins
 
-- Type: `Object`
-- Default: `{}`
+```js{}[nuxt.config.js]
+export default {
+  content: {
+    markdown: {
+      remarkPlugins: [
+        '~/plugins/my-custom-remark-plugin.js'
+      ]
+    }
+  }
+}
+```
 
-You can control the behaviour of links via this option. You can check here for [options](https://github.com/remarkjs/remark-external-links#api).
+- Provide options directly in the definition
 
 ```js{}[nuxt.config.js]
-content: {
-  markdown: {
-    externalLinks: {
-      target: '_self' // disable target="_blank"
-      rel: false // disable rel="nofollow noopener"
+export default {
+  content: {
+    markdown: {
+      remarkPlugins: [
+        ['remark-emoji', { emoticon: true }]
+      ]
     }
   }
 }
 ```
 
-### `markdown.footnotes`
+- Provide options using the name of the plugin in `camelCase`
 
-- Type: `Object`
-- Default: `{ inlineNotes: true }`
+```js{}[nuxt.config.js]
+export default {
+  content: {
+    markdown: {
+      // https://github.com/remarkjs/remark-external-links#options
+      remarkExternalLinks: {
+        target: '_self',
+        rel: 'nofollow'
+      }
+    }
+  }
+}
+```
+
+<base-alert>
+When adding a new plugin, make sure to install it in your dependencies:
+</base-alert>
+
+<code-group>
+  <code-block label="Yarn" active>
+
+  ```bash
+  yarn add remark-emoji
+  ```
+
+  </code-block>
+  <code-block label="NPM">
+
+  ```bash
+  npm install remark-emoji
+  ```
+
+  </code-block>
+</code-group>
+
+```js{}[nuxt.config.js]
+export default {
+  content: {
+    markdown: {
+      remarkPlugins: ['remark-emoji']
+    }
+  }
+}
+```
+
+### `markdown.remarkPlugins`
+
+- Type: `Array`
+- Default: `['remark-squeeze-paragraphs', 'remark-slug', 'remark-autolink-headings', 'remark-external-links', 'remark-footnotes']`
+- Version: **v2.0.0**
+
+> You can take a look at the list of [remark plugins](https://github.com/remarkjs/remark/blob/master/doc/plugins.md#list-of-plugins).
+
+### `markdown.rehypePlugins`
+
+- Type: `Array`
+- Default: `['rehype-minify-whitespace', 'rehype-sort-attribute-values', 'rehype-sort-attributes', 'rehype-raw']`
+- Version: **v2.0.0**
 
-You can control the behaviour of footnotes via this option. You can check here for [options](https://github.com/remarkjs/remark-footnotes#remarkusefootnotes-options).
+> You can take a look at the list of [rehype plugins](https://github.com/rehypejs/rehype/blob/master/doc/plugins.md#list-of-plugins).
 
 ### `markdown.prism.theme`
 
@@ -177,12 +268,19 @@ export default {
     fullTextSearchFields: ['title', 'description', 'slug', 'text'],
     nestedProperties: [],
     markdown: {
-      externalLinks: {},
-      footnotes: {
-        inlineNotes: true
-      },
-      basePlugins: ['remark-squeeze-paragraphs', 'remark-slug', 'remark-autolink-headings', 'remark-external-links', 'remark-footnotes'],
-      plugins: [],
+      remarkPlugins: [
+        'remark-squeeze-paragraphs',
+        'remark-slug',
+        'remark-autolink-headings',
+        'remark-external-links',
+        'remark-footnotes'
+      ],
+      rehypePlugins: [
+        'rehype-minify-whitespace',
+        'rehype-sort-attribute-values',
+        'rehype-sort-attributes',
+        'rehype-raw'
+      ],
       prism: {
         theme: 'prismjs/themes/prism.css'
       }
diff --git a/docs/content/en/writing.md b/docs/content/en/writing.md
index 56578aa5c..57426d072 100644
--- a/docs/content/en/writing.md
+++ b/docs/content/en/writing.md
@@ -89,10 +89,12 @@ It will be transformed to it's JSON AST structure, and by using the `nuxt-conten
 ```
 
 > The links in headings are empty and therefore hidden, so it's up to you to style them. For an example, try hovering one of the headers in these docs.
-  
+
 ### Links
 
-Links are transformed to add valid `target` and `rel` attributes. You can change this behaviour, see [configuration](/configuration#markdownexternallinks). Relative links are also automatically transformed to `nuxt-link` to provide navigation between page components with enhanced performance through smart prefetching.
+Links are transformed to add valid `target` and `rel` attributes using [remark-external-links](https://github.com/remarkjs/remark-external-links). You can check [here](/configuration#markdown) to learn how to configure this plugin.
+
+Relative links are also automatically transformed to [nuxt-link](https://nuxtjs.org/api/components-nuxt-link/) to provide navigation between page components with enhanced performance through smart prefetching.
 
 Here is an example using external, relative, markdown and html links:
 
@@ -116,7 +118,7 @@ title: Home
 
 ### Footnotes
 
-This module supports extended markdown syntax for footnotes.
+This module supports extended markdown syntax for footnotes using [remark-footnotes](https://github.com/remarkjs/remark-footnotes). You can check [here](/configuration#markdown) to learn how to configure this plugin.
 
 Here is an example using footnotes:
 
diff --git a/lib/index.js b/lib/index.js
index fb31c43c3..784ef3337 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -6,49 +6,23 @@ const defu = require('defu')
 const middleware = require('./middleware')
 const Database = require('./database')
 const WS = require('./ws')
+const { getDefaults, mergeConfig, processMarkdownOptions } = require('./utils')
 
-const defaults = {
-  watch: false,
-  apiPrefix: '_content',
-  dir: 'content',
-  fullTextSearchFields: ['title', 'description', 'slug', 'text'],
-  nestedProperties: [],
-  markdown: {
-    basePlugins: [
-      'remark-squeeze-paragraphs',
-      'remark-slug',
-      'remark-autolink-headings',
-      'remark-external-links',
-      'remark-footnotes'
-    ],
-    plugins: [
-    ],
-    footnotes: {
-      inlineNotes: true
-    },
-    externalLinks: {},
-    prism: {
-      theme: 'prismjs/themes/prism.css'
-    }
-  },
-  yaml: {},
-  csv: {}
-}
+module.exports = async function (moduleOptions) {
+  const isSSG = this.options.dev === false && (this.options.target === 'static' || this.options._generate)
 
-module.exports = async function () {
-  const isSSG =
-    this.options.dev === false &&
-    (this.options.target === 'static' || this.options._generate)
-  const options = defu(
-    {
-      watch: this.options.dev,
-      ...this.options.content
-    },
-    defaults
-  )
+  const { content = {} } = Object.assign({}, this.options)
+  Object.assign(content, moduleOptions)
 
+  const defaults = getDefaults({ dev: this.options.dev })
+
+  const mergedConfig = mergeConfig(content, defaults)
+  const options = defu(mergedConfig, defaults)
   options.dir = resolve(this.options.srcDir, options.dir)
 
+  // Load markdown plugins
+  processMarkdownOptions(options, this.nuxt.resolver.resolvePath)
+
   options.apiPrefixWithBase = options.apiPrefix
   if (this.options.router.base) {
     let baseRouter = this.options.router.base
@@ -197,3 +171,12 @@ module.exports = async function () {
 
 module.exports.Database = Database
 module.exports.middleware = middleware
+module.exports.getOptions = (userOptions = {}) => {
+  const defaults = getDefaults({ dev: process.env.NODE_ENV !== 'production' })
+  const mergedConfig = mergeConfig(userOptions, defaults)
+  const options = defu(mergedConfig, defaults)
+
+  processMarkdownOptions(options)
+
+  return options
+}
diff --git a/lib/parsers/markdown/index.js b/lib/parsers/markdown/index.js
index 22784addb..e87dbd606 100644
--- a/lib/parsers/markdown/index.js
+++ b/lib/parsers/markdown/index.js
@@ -1,13 +1,7 @@
 const matter = require('gray-matter')
-const { camelCase } = require('change-case')
 const unified = require('unified')
 const parse = require('remark-parse')
 const remark2rehype = require('remark-rehype')
-const minifyWhiteSpace = require('rehype-minify-whitespace')
-const sortValues = require('rehype-sort-attribute-values')
-const sortAttrs = require('rehype-sort-attributes')
-const raw = require('rehype-raw')
-const logger = require('consola').withScope('@nuxt/content')
 
 const handlers = require('./handlers')
 const jsonCompiler = require('./compilers/json')
@@ -15,7 +9,14 @@ const jsonCompiler = require('./compilers/json')
 class Markdown {
   constructor (options = {}) {
     this.options = options
-    this.plugins = [...options.basePlugins, ...options.plugins]
+  }
+
+  processPluginsFor (type, stream) {
+    for (const { instance, options } of this.options[`${type}Plugins`]) {
+      stream = stream.use(instance, options)
+    }
+
+    return stream
   }
 
   /**
@@ -64,22 +65,11 @@ class Markdown {
     return new Promise((resolve, reject) => {
       let stream = unified().use(parse)
 
-      for (const name of this.plugins) {
-        try {
-          const plugin = require(name)
-          const options = this.options[camelCase(name.replace('remark-', ''))]
-          stream = stream.use(plugin, options)
-        } catch (e) {
-          logger.warn(`${name} is not installed`)
-        }
-      }
+      stream = this.processPluginsFor('remark', stream)
+      stream = stream.use(remark2rehype, { handlers, allowDangerousHtml: true })
+      stream = this.processPluginsFor('rehype', stream)
 
       stream
-        .use(remark2rehype, { handlers, allowDangerousHtml: true })
-        .use(raw)
-        .use(minifyWhiteSpace)
-        .use(sortValues)
-        .use(sortAttrs)
         .use(jsonCompiler)
         .process(content, (error, file) => {
           /* istanbul ignore if */
diff --git a/lib/utils.js b/lib/utils.js
new file mode 100644
index 000000000..7342a12b1
--- /dev/null
+++ b/lib/utils.js
@@ -0,0 +1,90 @@
+const logger = require('consola').withScope('@nuxt/content')
+const { camelCase } = require('change-case')
+
+const getDefaults = ({ dev = false } = {}) => ({
+  watch: dev,
+  apiPrefix: '_content',
+  dir: 'content',
+  fullTextSearchFields: ['title', 'description', 'slug', 'text'],
+  nestedProperties: [],
+  markdown: {
+    remarkPlugins: [
+      'remark-squeeze-paragraphs',
+      'remark-slug',
+      'remark-autolink-headings',
+      'remark-external-links',
+      'remark-footnotes'
+    ],
+    rehypePlugins: [
+      'rehype-minify-whitespace',
+      'rehype-sort-attribute-values',
+      'rehype-sort-attributes',
+      'rehype-raw'
+    ],
+    prism: {
+      theme: 'prismjs/themes/prism.css'
+    }
+  },
+  yaml: {},
+  csv: {}
+})
+
+const mergeConfig = (content, defaults, options = {}) => {
+  return Object.entries(content).reduce((options, [key, value]) => {
+    const defaultValue = defaults[key]
+    if (value && typeof value !== 'function' && Array.isArray(defaultValue)) {
+      // Merge value with default value if array
+      value = defaultValue.concat(value)
+    } else if (typeof value === 'function') {
+      // Executed value functions and provide default value as param
+      value = value(defaultValue)
+    } else if (typeof value === 'object') {
+      value = mergeConfig(value, defaultValue || {}, options[key])
+    }
+
+    // Finally assign
+    options[key] = value
+    return options
+  }, options)
+}
+
+const processMarkdownPlugins = (type, markdown, resolvePath) => {
+  const plugins = []
+
+  for (const plugin of markdown[`${type}Plugins`]) {
+    let name
+    let options
+    let instance
+
+    if (typeof plugin === 'string') {
+      name = plugin
+      options = markdown[camelCase(name)]
+    } else if (Array.isArray(plugin)) {
+      [name, options] = plugin
+    }
+
+    try {
+      instance = require(resolvePath(name))
+
+      plugins.push({ name, instance, options })
+    } catch (e) {
+      logger.error(e.toString())
+    }
+  }
+
+  return plugins
+}
+
+const processMarkdownOptions = (options, resolvePath) => {
+  if (!resolvePath) {
+    resolvePath = path => path
+  }
+  options.markdown.remarkPlugins = processMarkdownPlugins('remark', options.markdown, resolvePath)
+  options.markdown.rehypePlugins = processMarkdownPlugins('rehype', options.markdown, resolvePath)
+}
+
+module.exports = {
+  getDefaults,
+  mergeConfig,
+  processMarkdownOptions
+}
diff --git a/test/options.test.js b/test/options.test.js
new file mode 100644
index 000000000..59ebad8d5
--- /dev/null
+++ b/test/options.test.js
@@ -0,0 +1,143 @@
+const { setup, loadConfig } = require('@nuxtjs/module-test-utils')
+
+describe('options', () => {
+  describe('defaults', () => {
+    let nuxt
+    let options
+
+    beforeAll(async () => {
+      ({ nuxt } = (await setup(loadConfig(__dirname))))
+      const { getOptions } = require('..')
+      options = getOptions()
+    }, 60000)
+
+    afterAll(async () => {
+      await nuxt.close()
+    })
+
+    test('', () => {
+      const remarkPlugins = [
+        'remark-squeeze-paragraphs',
+        'remark-slug',
+        'remark-autolink-headings',
+        'remark-external-links',
+        'remark-footnotes'
+      ]
+      const rehypePlugins = [
+        'rehype-minify-whitespace',
+        'rehype-sort-attribute-values',
+        'rehype-sort-attributes',
+        'rehype-raw'
+      ]
+
+      expect(options).toEqual(expect.objectContaining({
+        apiPrefix: '_content',
+        dir: 'content',
+        fullTextSearchFields: ['title', 'description', 'slug', 'text'],
+        nestedProperties: [],
+        csv: {},
+        yaml: {},
+        markdown: expect.objectContaining({
+          prism: {
+            theme: 'prismjs/themes/prism.css'
+          },
+          remarkPlugins: expect.arrayContaining(remarkPlugins.map(name => ({ name, instance: require(name), options: undefined }))),
+          rehypePlugins: expect.arrayContaining(rehypePlugins.map(name => ({ name, instance: require(name), options: undefined })))
+        })
+      }))
+    })
+  })
+
+  describe('overriding plugin options', () => {
+    let nuxt
+    let options
+
+    const config = {
+      markdown: {
+        remarkSlug: { option: 'a' }
+      }
+    }
+
+    beforeAll(async () => {
+      ({ nuxt } = (await setup(loadConfig(__dirname))))
+      const { getOptions } = require('..')
+      options = getOptions(config)
+    }, 60000)
+
+    afterAll(async () => {
+      await nuxt.close()
+    })
+
+    test('', () => {
+      expect(options).toEqual(expect.objectContaining({
+        markdown: expect.objectContaining({
+          remarkPlugins: expect.arrayContaining([
+            expect.objectContaining({ name: 'remark-slug', options: { option: 'a' } })
+          ])
+        })
+      }))
+    })
+  })
+
+  describe('adding not installed plugins', () => {
+    let nuxt
+    let options
+
+    const config = {
+      markdown: {
+        remarkPlugins: ['remark-toto']
+      }
+    }
+
+    beforeAll(async () => {
+      ({ nuxt } = (await setup(loadConfig(__dirname))))
+      const { getOptions } = require('..')
+      options = getOptions(config)
+    }, 60000)
+
+    afterAll(async () => {
+      await nuxt.close()
+    })
+
+    test('', () => {
+      expect(options).toEqual(expect.objectContaining({
+        markdown: expect.objectContaining({
+          remarkPlugins: expect.not.arrayContaining([
+            expect.objectContaining({ name: 'remark-toto' })
+          ])
+        })
+      }))
+    })
+  })
+
+  describe('adding plugins with options', () => {
+    let nuxt
+    let options
+
+    const config = {
+      markdown: {
+        remarkPlugins: () => [['remark-slug', { option: 'a' }]]
+      }
+    }
+
+    beforeAll(async () => {
+      ({ nuxt } = (await setup(loadConfig(__dirname))))
+      const { getOptions } = require('..')
+      options = getOptions(config)
+    }, 60000)
+
+    afterAll(async () => {
+      await nuxt.close()
+    })
+
+    test('', () => {
+      expect(options).toEqual(expect.objectContaining({
+        markdown: expect.objectContaining({
+          remarkPlugins: expect.not.arrayContaining([
+            expect.objectContaining({ name: 'remark-toto', options: { option: 'a' } })
+          ])
+        })
+      }))
+    })
+  })
+})