feat: nuxt 3 support (#89)

BREAKING CHANGE: drop node 14 support BREAKING CHANGE: different field config format (see readme) BREAKING CHANGE: highlighter: undefined doesn't work anymore, instead set the highlighter to a function (see readme)
dword-design · Jun 14, 2023 · b8d05a0 · b8d05a0
1 parent 90304a9
commit b8d05a0
Show file tree

Hide file tree

Showing 15 changed files with 5,112 additions and 6,488 deletions.
diff --git a/.baserc.json b/.baserc.json
@@ -1,11 +1,18 @@
 {
   "name": "@dword-design/node",
-  "supportedNodeVersions": [14, 16],
+  "nodeVersion": 18,
+  "supportedNodeVersions": [16, 18],
   "seeAlso": [
     { "repository": "nuxt-content-git", "description": "Adds a property to each @nuxt/content document containing the raw HTML body, rendered from markdown." },
     { "repository": "nuxt-mail", "description": "Adds email sending capability to a Nuxt.js app. Adds a server route, an injected variable, and uses nodemailer to send emails." },
     { "repository": "nuxt-route-meta", "description": "Adds Nuxt page data to route meta at build time." },
     { "repository": "nuxt-modernizr", "description": "Adds a Modernizr build to your Nuxt.js app." },
     { "repository": "nuxt-mermaid-string", "description": "Embed a Mermaid diagram in a Nuxt.js app by providing its diagram string." }
-  ]
+  ],
+  "eslintConfig": {
+    "extends": "@dword-design/eslint-config",
+    "rules": {
+      "import/no-unresolved": ["error", { "ignore": ["#imports"] }]
+    }
+  }
 }
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -2,6 +2,6 @@
   "features": {
     "ghcr.io/devcontainers/features/docker-in-docker:2": {}
   },
-  "image": "mcr.microsoft.com/devcontainers/javascript-node:0-16",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:0-18",
   "updateContentCommand": "yarn --frozen-lockfile"
 }
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -1,3 +1,13 @@
 {
-  "extends": "@dword-design/eslint-config"
+  "extends": "@dword-design/eslint-config",
+  "rules": {
+    "import/no-unresolved": [
+      "error",
+      {
+        "ignore": [
+          "#imports"
+        ]
+      }
+    ]
+  }
 }
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -17,7 +17,7 @@ jobs:
             github.event.pull_request.head.ref || '' }}
       - uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
       - run: git config --global user.email "actions@github.com"
       - run: git config --global user.name "GitHub Actions"
       - run: yarn --frozen-lockfile
@@ -54,20 +54,20 @@ jobs:
         with:
           name: Image Snapshot Diffs
           path: "**/__image_snapshots__/__diff_output__"
-      - if: matrix.os == 'ubuntu-latest' && matrix.node == 16
+      - if: matrix.os == 'ubuntu-latest' && matrix.node == 18
         uses: codecov/codecov-action@v3
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
     strategy:
       matrix:
         include:
-          - node: 14
-            os: ubuntu-latest
           - node: 16
             os: ubuntu-latest
-          - node: 16
+          - node: 18
+            os: ubuntu-latest
+          - node: 18
             os: macos-latest
-          - node: 16
+          - node: 18
             os: windows-latest
 name: build
 on:

diff --git a/.gitpod.Dockerfile b/.gitpod.Dockerfile
@@ -6,7 +6,7 @@ RUN sudo apt-get install git-lfs
 RUN git lfs install
 
 # https://www.gitpod.io/docs/languages/javascript
-RUN bash -c 'VERSION="16"       && source $HOME/.nvm/nvm.sh && nvm install $VERSION       && nvm use $VERSION && nvm alias default $VERSION'
+RUN bash -c 'VERSION="18"       && source $HOME/.nvm/nvm.sh && nvm install $VERSION       && nvm use $VERSION && nvm alias default $VERSION'
 
 RUN echo "\nexport PATH=$(yarn global bin):\$PATH" >> /home/gitpod/.bashrc
 

diff --git a/.gitpod.yml b/.gitpod.yml
@@ -9,9 +9,13 @@ tasks:
       gitpod-env-per-project >> /home/gitpod/.bashrc && source /home/gitpod/.bashrc
     init: |-
       git config --global user.name "Sebastian Landwehr"
-      git lfs pull && yarn --frozen-lockfile
+      git config diff.lfs.textconv cat
+      git lfs pull
+      yarn --frozen-lockfile
 vscode:
   extensions:
     - https://sebastianlandwehr.com/vscode-extensions/karlito40.fix-irregular-whitespace-0.1.1.vsix
     - https://sebastianlandwehr.com/vscode-extensions/adrianwilczynski.toggle-hidden-1.0.2.vsix
     - octref.vetur@0.33.1
+    - Tobermory.es6-string-html
+    - zjcompt.es6-string-javascript
diff --git a/README.md b/README.md
@@ -67,59 +67,172 @@ $ yarn add nuxt-content-body-html
 
 Sometimes you need the raw HTML code of `@nuxt/content` documents for processing. A frequent use case is to generate an RSS feed and to add the HTML as `content:encoded`. The module will use the default remark and rehype plugins. You can also add additional plugins.
 
-## Usage
+## Nuxt 3
 
-Add the module to your `nuxt.config.js` file **before** `@nuxt/content`:
+Add the module to your `nuxt.config.js` file:
 
 ```js
 export default {
   modules: [
+    '@nuxt/content',
     'nuxt-content-body-html',
+  },
+}
+```
+
+To generate the HTML, you have two options: 1. Add fields to the module config and 2. use the `useNuxtContentBodyHtml` composable. If you just need a simple HTML version of your markdown content, the module config is fine. But if you want to add extra remark or rehype plugins involving functions, you will need to use the composable because Nuxt won't be able to serialize it into the runtime config.
+
+### Module config
+
+```js
+export default {
+  modules: [
     '@nuxt/content',
+    ['nuxt-content-body-html', {
+      fields: {
+        bodyHtml: {},
+      },
+    }],
   },
 }
 ```
 
-This will add a `doc.bodyHtml` property to all documents with the rendered body HTML code.
+This is the simplest way of generating the `bodyHtml` field into the file objects.
+
+### Composable
 
-It is also possible specifiy the name of the property like so:
+Add a Nitro plugin to `server/plugins`. We will hook into `content:file:beforeParse` and add our HTML code by calling the composable. Unfortunately, there is currently an [open issue in @nuxt/content](https://github.com/nuxt/content/issues/2056) that does not persist variables added in `content:file:beforeParse`. So we will have to store them and restore them in `content:file:afterParse`. Hopefully this will be fixed soon.
+
+```js
+// server/plugins/body-html.js
+
+import { defineNitroPlugin, useNuxtContentBodyHtml } from '#imports'
+
+const nuxtContentBodyHtml = useNuxtContentBodyHtml()
+
+export default defineNitroPlugin(nitroApp => {
+  const bodyHtmls = {}
+
+  nitroApp.hooks.hook('content:file:beforeParse', async file =>
+    bodyHtmls[file._id] = await nuxtContentBodyHtml.generate(file)
+  )
+  nitroApp.hooks.hook('content:file:afterParse', file => (file.bodyHtml = bodyHtmls[file._id]))
+})
+```
+
+### Adding Remark and Rehype plugins
+
+In some cases you will want to add additional plugins to customize the HTML. E.g. in an RSS feed you want to have absolute URLs. You can add plugins to the field configs and the composable like so:
 
 ```js
 export default {
   modules: [
-    ['nuxt-content-body-html', { fieldName: 'html' }],
     '@nuxt/content',
-  ],
+    ['nuxt-content-body-html', {
+      fields: {
+        bodyHtml: {
+          remarkPlugins: {
+            'remark-foo': {},
+          },
+          rehypePlugins: {
+            'rehype-foo: {},
+          },
+        },
+      },
+    }],
+  },
 }
 ```
 
-Then you can access it via `doc.bodyHtml`.
+```js
+await useNuxtContentBodyHtml.generate(file, {
+  remarkPlugins: {
+    'remark-foo': {},
+  },
+  rehypePlugins: {
+    'rehype-foo: {},
+  },
+})
+```
 
-## Adding more remark and rehype plugins
+### Enabling the highlighter
 
-It is possible to add additional plugins via the module config like so:
+You can easily enable syntax highlighting like so:
 
 ```js
 export default {
   modules: [
+    '@nuxt/content',
     ['nuxt-content-body-html', {
-      remarkPlugins: [
-        'plugin1',
-        ['plugin2', { /* options */ }],
-      ],
-      rehypePlugins: [
-        'plugin1',
-        ['plugin2', { /* options */ }],
-      ],
+      fields: {
+        bodyHtml: { highlight: true },
+      },
+    }],
+  },
+}
+```
+
+```js
+await useNuxtContentBodyHtml.generate(file, { highlight: true })
+```
+
+## Nuxt 2 and @nuxt/content@^1
+
+`nuxt-content-body-html` works similarly for Nuxt 2 with some minor differences. Firstly, you need to add the module to your `nuxt.config.js` file **before** `@nuxt/content`:
+
+```js
+export default {
+  modules: [
+    'nuxt-content-body-html',
+    '@nuxt/content',
+  },
+}
+```
+
+Then, the HTML code will be generated in module context and not in Nitro context, so you can completely configure your fields via the module config and you do not need a composable.
+
+For convenience, if you do not configure any field, a `bodyHtml` field will be configured by default. So the above config will already generate a field.
+
+To add fields or have a different name for the field, you can add fields like so:
+
+```js
+export default {
+  modules: [
+    ['nuxt-content-body-html', {
+      fooHtml: {},
+    }],
+    '@nuxt/content',
+  ],
+}
+```
+
+### Plugins
+
+You can also add plugins to the config. Note that the plugins are arrays:
+
+```js
+export default {
+  modules: [
+    ['nuxt-content-body-html', {
+      fooHtml: {
+        remarkPlugins: [
+          'plugin1',
+          ['plugin2', { /* options */ }],
+        ],
+        rehypePlugins: [
+          'plugin1',
+          ['plugin2', { /* options */ }],
+        ],
+      },
     }],
     '@nuxt/content',
   ],
 }
 ```
 
-## Overriding or disabling the highlighter
+### Overriding or disabling the highlighter
 
-You can explicitly override or disable the highlighter by passing it as as an option:
+In `@nuxt/content^1` the highlighter is enabled by default. You can explicitly override or disable the highlighter by setting it in the config:
 
 ```js
 export default {
@@ -128,8 +241,8 @@ export default {
       // Pass a custom highlighter
       highlighter: customHighlighter,
 
-      // Disable the highlighter
-      highlighter: undefined,
+      // Disable the highlighter by setting a noop function
+      highlighter: code => `<pre><code class="language-js">${code}</code></pre>`,
     }],
     '@nuxt/content',
   ],
@@ -140,24 +253,46 @@ export default {
 
 You can customize the module so that you can use the resulting HTML code for RSS feeds.
 
-Firstly, RSS feeds require URLs to be absolute. You can use [rehype-urls](https://github.com/brechtcs/rehype-urls) to make relative URLs absolute. Also, you want to disable the highlighter, so that the code tags are remained.
+Firstly, RSS feeds require URLs to be absolute. You can use [rehype-urls](https://github.com/brechtcs/rehype-urls) to make relative URLs absolute. At the time of writing, the npm version is not compatible with `@nuxt/content@^2`, you will need to fix the issue in [this PR](https://github.com/brechtcs/rehype-urls/pull/3).
 
 ```js
+// nuxt.config.js
+
 // Set process.env.BASE_URL to the domain to prepend
 
 export default {
+  runtimeConfig: {
+    baseUrl: process.env.BASE_URL,
+  },
   modules: [
-    ['nuxt-content-body-html', {
-      highlighter: undefined,
-      rehypePlugins: [
-        ['rehype-urls', url => (url.host ? url : new URL(url.href, process.env.BASE_URL))],
-      ],
-    }],
     '@nuxt/content',
+    'nuxt-content-body-html',
   ],
 }
 ```
 
+```js
+// server/plugins/body-html.js
+
+import { defineNitroPlugin, useNuxtContentBodyHtml, useRuntimeConfig } from '#imports'
+
+const { baseUrl } = useRuntimeConfig()
+const nuxtContentBodyHtml = useNuxtContentBodyHtml()
+
+export default defineNitroPlugin(nitroApp => {
+  const bodyHtmls = {}
+
+  nitroApp.hooks.hook('content:file:beforeParse', async file =>
+    bodyHtmls[file._id] = await nuxtContentBodyHtml.generate(file, {
+      rehypePlugins: {
+        'rehype-urls', { transform: url => (url.host ? url : new URL(url.href, baseUrl)) },
+      },
+    })
+  )
+  nitroApp.hooks.hook('content:file:afterParse', file => (file.bodyHtml = bodyHtmls[file._id]))
+})
+```
+
 <!-- LICENSE/ -->
 ## Contribute