From a4903ae1f5bb24cdb075b15f374135e7da554511 Mon Sep 17 00:00:00 2001 From: aaronamm Date: Thu, 17 Nov 2022 20:08:40 +0700 Subject: [PATCH] feat: add gatsbyRemarkPlugins option (#146) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: João Pedro Schmitz --- .changeset/pink-feet-brake.md | 6 ++ .../gatsby-theme-docs-core/gatsby-config.js | 11 +++- .../util/with-default.js | 3 + .../gatsby-theme-docs/gatsby-config.js | 8 +-- examples/gatsby-theme-docs/gatsby-config.js | 1 + .../gatsby-theme-docs/src/config/sidebar.yml | 2 + .../src/docs/usage/remark-plugins.md | 66 +++++++++++++++++++ 7 files changed, 91 insertions(+), 6 deletions(-) create mode 100644 .changeset/pink-feet-brake.md create mode 100644 examples/gatsby-theme-docs/src/docs/usage/remark-plugins.md diff --git a/.changeset/pink-feet-brake.md b/.changeset/pink-feet-brake.md new file mode 100644 index 0000000..be2e1c5 --- /dev/null +++ b/.changeset/pink-feet-brake.md @@ -0,0 +1,6 @@ +--- +'@rocketseat/gatsby-theme-docs': minor +'@rocketseat/gatsby-theme-docs-core': minor +--- + +Add `gatsbyRemarkPlugins` option diff --git a/@rocketseat/gatsby-theme-docs-core/gatsby-config.js b/@rocketseat/gatsby-theme-docs-core/gatsby-config.js index 7497c70..28d3d57 100644 --- a/@rocketseat/gatsby-theme-docs-core/gatsby-config.js +++ b/@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`], }, diff --git a/@rocketseat/gatsby-theme-docs-core/util/with-default.js b/@rocketseat/gatsby-theme-docs-core/util/with-default.js index 3efbe9d..78a0ed8 100644 --- a/@rocketseat/gatsby-theme-docs-core/util/with-default.js +++ b/@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, }; }; diff --git a/@rocketseat/gatsby-theme-docs/gatsby-config.js b/@rocketseat/gatsby-theme-docs/gatsby-config.js index 1e7d315..48cad5f 100644 --- a/@rocketseat/gatsby-theme-docs/gatsby-config.js +++ b/@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`, diff --git a/examples/gatsby-theme-docs/gatsby-config.js b/examples/gatsby-theme-docs/gatsby-config.js index 53c6b2a..cb9580f 100644 --- a/examples/gatsby-theme-docs/gatsby-config.js +++ b/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: [], }, }, { diff --git a/examples/gatsby-theme-docs/src/config/sidebar.yml b/examples/gatsby-theme-docs/src/config/sidebar.yml index 3c4931e..4000fa0 100644 --- a/examples/gatsby-theme-docs/src/config/sidebar.yml +++ b/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 diff --git a/examples/gatsby-theme-docs/src/docs/usage/remark-plugins.md b/examples/gatsby-theme-docs/src/docs/usage/remark-plugins.md new file mode 100644 index 0000000..fc475b6 --- /dev/null +++ b/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.