Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(v2): add remark-admonitions to @docusaurus/preset-classic #2224

Merged
merged 7 commits into from
Feb 8, 2020
Merged

feat(v2): add remark-admonitions to @docusaurus/preset-classic #2224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7378d90
feat(v2): add remark-admonitions
elviswolcott Jan 17, 2020
947af07
feat(v2): add admonitions to style guide
elviswolcott Jan 17, 2020
ec11eb7
style: cleanup changes
elviswolcott Jan 17, 2020
7022025
docs(v2): document how to use admonitions
elviswolcott Jan 19, 2020
1fe22a8
docs(v2): use proper package name
elviswolcott Jan 19, 2020
b34038a
docs(v2): add link to remark-admonitions docs
elviswolcott Jan 23, 2020
bc60549
style(v2): clean up addAdmonitions
elviswolcott Jan 23, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions packages/docusaurus-init/templates/classic/docs/doc1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO caution and warning are synonyms. I think it's more conventional for yellow to be caution/warning and red for danger.

See VuePress' version - https://vuepress.vuejs.org/guide/markdown.html#custom-containers

Copy link
Contributor Author

@elviswolcott elviswolcott Jan 23, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I already have an alias of danger -> caution. I went with those words so that it is fully backwards compatible with remarkable-admonitions so that anyone upgrading their site will get the expected results.

I based the ordering of caution warning danger on the guidelines provided here favoloso/remarkable-admonitions#4

I can switch around the aliases (i.e. make it warning and danger with caution -> warning) for consistency with Infima over backwards compatibility.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@yangshun which approach would you prefer?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was just a nit comment, it's fine as-is 😄

This is a caution
:::

:::warning
This is a warning
:::
24 changes: 24 additions & 0 deletions packages/docusaurus-init/templates/facebook/docs/doc1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
:::
3 changes: 2 additions & 1 deletion packages/docusaurus-preset-classic/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
29 changes: 27 additions & 2 deletions packages/docusaurus-preset-classic/src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: [
Expand All @@ -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',
Expand Down
3 changes: 2 additions & 1 deletion packages/docusaurus-theme-classic/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
6 changes: 5 additions & 1 deletion packages/docusaurus-theme-classic/src/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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',
elviswolcott marked this conversation as resolved.
Show resolved Hide resolved
customCss,
];
},

injectHtmlTags() {
Expand Down
21 changes: 20 additions & 1 deletion website/docs/markdown-features.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
:::

---

Expand Down Expand Up @@ -465,3 +467,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.
:::
21 changes: 21 additions & 0 deletions website/docs/presets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: {},
elviswolcott marked this conversation as resolved.
Show resolved Hide resolved
},
},
],
],
};
```

<!--

Advanced guide on using and configuring presets
Expand Down