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 b64d4d67bf..48725596c1 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 8fddcad479..4372d1d2a3 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 63d23ca143..1b5a3903d8 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 34584be04c..8e73325a43 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 78653f0d0d..2aa552866c 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 0f09eab682..9f84af2a4c 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 e9c6d63f72..a302e08cfb 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 e7a13dccc9..77fc6e005d 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: {}, + }, + }, + ], + ], +}; +``` +