From 0fa080c39c86a75ed4b36c01203ca9830f464542 Mon Sep 17 00:00:00 2001 From: Elvis Wolcott Date: Sat, 8 Feb 2020 05:28:47 -0600 Subject: [PATCH] feat(v2): add remark-admonitions to @docusaurus/preset-classic (#2224) * feat(v2): add remark-admonitions * feat(v2): add admonitions to style guide * style: cleanup changes * docs(v2): document how to use admonitions * docs(v2): use proper package name * docs(v2): add link to remark-admonitions docs * style(v2): clean up addAdmonitions --- .../templates/classic/docs/doc1.md | 24 +++++++++++++++ .../templates/facebook/docs/doc1.md | 24 +++++++++++++++ .../docusaurus-preset-classic/package.json | 3 +- .../docusaurus-preset-classic/src/index.js | 29 +++++++++++++++++-- .../docusaurus-theme-classic/package.json | 3 +- .../docusaurus-theme-classic/src/index.js | 6 +++- website/docs/markdown-features.mdx | 21 +++++++++++++- website/docs/presets.md | 21 ++++++++++++++ 8 files changed, 125 insertions(+), 6 deletions(-) diff --git a/packages/docusaurus-init/templates/classic/docs/doc1.md b/packages/docusaurus-init/templates/classic/docs/doc1.md index b64d4d67bf27..48725596c112 100644 --- a/packages/docusaurus-init/templates/classic/docs/doc1.md +++ b/packages/docusaurus-init/templates/classic/docs/doc1.md @@ -166,3 +166,27 @@ Here's a line for us to start with. This line is separated from the one above by two newlines, so it will be a _separate paragraph_. This line is also a separate paragraph, but... This line is only separated by a single newline, so it's a separate line in the _same paragraph_. + +--- + +## Admonitions + +:::note +This is a note +::: + +:::tip +This is a tip +::: + +:::important +This is important +::: + +:::caution +This is a caution +::: + +:::warning +This is a warning +::: diff --git a/packages/docusaurus-init/templates/facebook/docs/doc1.md b/packages/docusaurus-init/templates/facebook/docs/doc1.md index 8fddcad47912..4372d1d2a351 100644 --- a/packages/docusaurus-init/templates/facebook/docs/doc1.md +++ b/packages/docusaurus-init/templates/facebook/docs/doc1.md @@ -166,3 +166,27 @@ Here's a line for us to start with. This line is separated from the one above by two newlines, so it will be a _separate paragraph_. This line is also a separate paragraph, but... This line is only separated by a single newline, so it's a separate line in the _same paragraph_. + +--- + +## Admonitions + +:::note +This is a note +::: + +:::tip +This is a tip +::: + +:::important +This is important +::: + +:::caution +This is a caution +::: + +:::warning +This is a warning +::: diff --git a/packages/docusaurus-preset-classic/package.json b/packages/docusaurus-preset-classic/package.json index 63d23ca143c6..1b5a3903d870 100644 --- a/packages/docusaurus-preset-classic/package.json +++ b/packages/docusaurus-preset-classic/package.json @@ -15,7 +15,8 @@ "@docusaurus/plugin-google-gtag": "^2.0.0-alpha.40", "@docusaurus/plugin-sitemap": "^2.0.0-alpha.40", "@docusaurus/theme-classic": "^2.0.0-alpha.40", - "@docusaurus/theme-search-algolia": "^2.0.0-alpha.40" + "@docusaurus/theme-search-algolia": "^2.0.0-alpha.40", + "remark-admonitions": "^1.1.0" }, "peerDependencies": { "@docusaurus/core": "^2.0.0" diff --git a/packages/docusaurus-preset-classic/src/index.js b/packages/docusaurus-preset-classic/src/index.js index 34584be04c3f..8e73325a4342 100644 --- a/packages/docusaurus-preset-classic/src/index.js +++ b/packages/docusaurus-preset-classic/src/index.js @@ -4,12 +4,37 @@ * This source code is licensed under the MIT license found in the * LICENSE file in the root directory of this source tree. */ +const admonitions = require('remark-admonitions'); + +const addAdmonitions = pluginOptions => { + if (pluginOptions == null) { + return { + remarkPlugins: [admonitions], + }; + } + if (pluginOptions.admonitions === false) { + return pluginOptions; + } + const admonitionsOptions = { + remarkPlugins: (pluginOptions.remarkPlugins || []).concat([ + admonitions, + pluginOptions.admonitions || {}, + ]), + }; + return { + ...pluginOptions, + ...admonitionsOptions, + }; +}; module.exports = function preset(context, opts = {}) { const {siteConfig = {}} = context; const {themeConfig} = siteConfig; const {algolia, googleAnalytics, gtag} = themeConfig; + const docs = addAdmonitions(opts.docs); + const blog = addAdmonitions(opts.blog); + const isProd = process.env.NODE_ENV === 'production'; return { themes: [ @@ -18,8 +43,8 @@ module.exports = function preset(context, opts = {}) { algolia && '@docusaurus/theme-search-algolia', ], plugins: [ - ['@docusaurus/plugin-content-docs', opts.docs], - ['@docusaurus/plugin-content-blog', opts.blog], + ['@docusaurus/plugin-content-docs', docs], + ['@docusaurus/plugin-content-blog', blog], ['@docusaurus/plugin-content-pages', opts.pages], isProd && googleAnalytics && '@docusaurus/plugin-google-analytics', isProd && gtag && '@docusaurus/plugin-google-gtag', diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json index 78653f0d0d5f..2aa552866c19 100644 --- a/packages/docusaurus-theme-classic/package.json +++ b/packages/docusaurus-theme-classic/package.json @@ -16,7 +16,8 @@ "parse-numeric-range": "^0.0.2", "prism-react-renderer": "^1.0.2", "react-router-dom": "^5.1.2", - "react-toggle": "^4.1.1" + "react-toggle": "^4.1.1", + "remark-admonitions": "^1.1.0" }, "peerDependencies": { "@docusaurus/core": "^2.0.0", diff --git a/packages/docusaurus-theme-classic/src/index.js b/packages/docusaurus-theme-classic/src/index.js index 0f09eab68218..9f84af2a4ccd 100644 --- a/packages/docusaurus-theme-classic/src/index.js +++ b/packages/docusaurus-theme-classic/src/index.js @@ -55,7 +55,11 @@ module.exports = function(context, options) { }, getClientModules() { - return ['infima/dist/css/default/default.css', customCss]; + return [ + 'infima/dist/css/default/default.css', + 'remark-admonitions/styles/infima.css', + customCss, + ]; }, injectHtmlTags() { diff --git a/website/docs/markdown-features.mdx b/website/docs/markdown-features.mdx index e9c6d63f72f6..a302e08cfbbb 100644 --- a/website/docs/markdown-features.mdx +++ b/website/docs/markdown-features.mdx @@ -16,7 +16,9 @@ Docusaurus 2 uses modern tooling to help you compose your interactive documentat In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example. -**Note:** All the following content assumes you are using `docusaurus-preset-classic`. +:::important +All the following content assumes you are using `@docusaurus/preset-classic`. +::: --- @@ -467,3 +469,20 @@ class HelloWorld { You may want to implement your own `` abstraction if you find the above approach too verbose. We might just implement one in future for convenience. + +### Callouts/admonitions + +In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. +Admonitions are wrapped by a set of 3 colons. + +Example: + + ```markdown + :::tip Title + The and title *can* include markdown. + ::: + ``` + +:::tip Title +The content and title *can* include markdown. +::: \ No newline at end of file diff --git a/website/docs/presets.md b/website/docs/presets.md index e7a13dccc9f7..77fc6e005df9 100644 --- a/website/docs/presets.md +++ b/website/docs/presets.md @@ -112,6 +112,27 @@ module.exports = { }; ``` +In addition to these plugins and themes, `@docusaurus/theme-classic` adds [`remark-admonitions`](https://github.com/elviswolcott/remark-admonitions) as a remark plugin to `@docusaurus/plugin-content-blog` and `@docusaurus/plugin-content-docs`. + +The `admonitions` key will be passed as the [options](https://github.com/elviswolcott/remark-admonitions#options) to `remark-admonitions`. Passing `false` will prevent the plugin from being added to MDX. + +```js +// docusaurus.config.js +module.exports = { + presets: [ + [ + '@docusaurus/preset-classic', + { + docs: { + // options for remark-admonitions + admonitions: {}, + }, + }, + ], + ], +}; +``` +