feat: add gatsbyRemarkPlugins option (#146)

Co-authored-by: João Pedro Schmitz <oi@joaopedro.cc>

.changeset/pink-feet-brake.md

@@ -0,0 +1,6 @@
+---
+'@rocketseat/gatsby-theme-docs': minor
+'@rocketseat/gatsby-theme-docs-core': minor
+---
+
+Add `gatsbyRemarkPlugins` option

@rocketseat/gatsby-theme-docs-core/gatsby-config.js

@@ -5,8 +5,14 @@ const camelCase = require('lodash.camelcase');
 const upperFirst = (text) => text.charAt(0).toUpperCase() + text.slice(1);
 
 module.exports = (options) => {
-  const { basePath, configPath, docsPath, yamlFilesPath, withMdx } =
-    withDefault(options);
+  const {
+    basePath,
+    configPath,
+    docsPath,
+    yamlFilesPath,
+    withMdx,
+    gatsbyRemarkPlugins,
+  } = withDefault(options);
 
   return {
     siteMetadata: {
@@ -77,6 +83,7 @@ module.exports = (options) => {
             },
             `gatsby-remark-responsive-iframe`,
             `gatsby-remark-copy-linked-files`,
+            ...gatsbyRemarkPlugins,
           ],
           plugins: [`gatsby-remark-autolink-headers`, `gatsby-remark-images`],
         },

@rocketseat/gatsby-theme-docs-core/util/with-default.js

@@ -7,6 +7,8 @@ module.exports = (themeOptions) => {
   const baseDir = themeOptions.baseDir || ``;
   const withMdx =
     themeOptions.withMdx === undefined ? true : themeOptions.withMdx;
+  const gatsbyRemarkPlugins = themeOptions.gatsbyRemarkPlugins || [];
+
   const { githubUrl, repositoryUrl = '' } = themeOptions;
 
   return {
@@ -19,5 +21,6 @@ module.exports = (themeOptions) => {
     repositoryUrl,
     withMdx,
     branch,
+    gatsbyRemarkPlugins,
   };
 };

@rocketseat/gatsby-theme-docs/gatsby-config.js

@@ -1,7 +1,7 @@
 const withDefault = require('@rocketseat/gatsby-theme-docs-core/util/with-default');
 
 module.exports = (options) => {
-  const themeOtions = withDefault(options);
+  const themeOptions = withDefault(options);
 
   return {
     siteMetadata: {
@@ -13,13 +13,13 @@ module.exports = (options) => {
       siteAuthor: `@jpedroschmitz`,
       siteImage: `/banner.png`,
       siteLanguage: `en`,
-      basePath: themeOtions.basePath,
-      docsPath: themeOtions.docsPath,
+      basePath: themeOptions.basePath,
+      docsPath: themeOptions.docsPath,
     },
     plugins: [
       {
         resolve: `@rocketseat/gatsby-theme-docs-core`,
-        options: themeOtions,
+        options: themeOptions,
       },
       `gatsby-plugin-catch-links`,
       `gatsby-plugin-emotion`,

examples/gatsby-theme-docs/gatsby-config.js

@@ -20,6 +20,7 @@ module.exports = {
         yamlFilesPath: `src/yamlFiles`,
         repositoryUrl: `https://github.com/jpedroschmitz/rocketdocs`,
         baseDir: `examples/gatsby-theme-docs`,
+        gatsbyRemarkPlugins: [],
       },
     },
     {

examples/gatsby-theme-docs/src/config/sidebar.yml

@@ -14,6 +14,8 @@
       link: '/usage/shadowing'
     - label: 'Using YAML files'
       link: '/usage/using-yaml-files'
+    - label: 'Remark Plugins'
+      link: '/usage/remark-plugins'
 - label: More
   items:
     - label: FAQ

examples/gatsby-theme-docs/src/docs/usage/remark-plugins.md

@@ -0,0 +1,66 @@
+---
+title: Remark plugins
+description: Learn how to use Remark plugins in Rocket Docs.
+---
+
+To use a Remark plugin, you need to set the plugin name on this theme's `gatsbyRemarkPlugins` option.
+
+## Example usage
+
+Given that we want to use [Graphviz](https://graphviz.org/) in our Markdown files, we need to install the Remark plugin and add it on to `gatsbyRemarkPlugins` option on `gatsby.config.js`.
+
+```sh
+# Using Yarn:
+yarn add gatsby-remark-graphviz
+# Using NPM:
+npm i gatsby-remark-graphviz
+```
+
+```js title=gatsby-config.js
+module.exports = {
+  siteMetadata: {
+    // ...
+  },
+  plugins: [
+    {
+      resolve: `@rocketseat/gatsby-theme-docs`,
+      options: {
+        // ...
+        gatsbyRemarkPlugins: [
+          {
+            `gatsby-remark-graphviz`,
+          }
+        ]
+      },
+    }
+  ]
+}
+```
+
+## Using a custom Remark Transformer plugin
+
+If you use a local plugin, you must point to its location in the project through `require.resolve`.
+
+```js title=gatsby-config.js
+module.exports = {
+  siteMetadata: {
+    // ...
+  },
+  plugins: [
+    {
+      resolve: `@rocketseat/gatsby-theme-docs`,
+      options: {
+        // ...
+        gatsbyRemarkPlugins: [
+          {
+            `gatsby-remark-graphviz`,
+            resolve: require.resolve(`./plugins/gatsby-remark-purple-headers`)
+          }
+        ]
+      },
+    }
+  ]
+}
+```
+
+For more information on how to create a Remark Transformer plugin, please refer to the [Creating a Remark Transformer Plugin](https://www.gatsbyjs.com/tutorial/remark-plugin-tutorial/) document.