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

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
+:::

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
+:::

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"

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-docs', docs],
-      ['@docusaurus/plugin-content-blog', opts.blog],
+      ['@docusaurus/plugin-content-blog', blog],
       ['@docusaurus/plugin-content-pages', opts.pages],
       isProd && googleAnalytics && '@docusaurus/plugin-google-analytics',
       isProd && gtag && '@docusaurus/plugin-google-gtag',

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",

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() {

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 {
 </Tabs>
 
 You may want to implement your own `<MultiLanguageCode />` 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.
+:::

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: {},
+        },
+      },
+    ],
+  ],
+};
+```
+
 <!--
 
 Advanced guide on using and configuring presets