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

Jump to bottom

docs: add documentation for custom admonitions #5625

Closed
wants to merge 1 commit into from
Closed

docs: add documentation for custom admonitions #5625

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 32 additions & 0 deletions website/docs/guides/markdown-features/markdown-features-admonitions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,3 +121,35 @@ import TabItem from '@theme/TabItem';
```

:::

## Custom Admonitions

If you're using `@docusaurus/preset-classic`, you can create custom admonitions by adding them to your website's `docusaurus.config.js`.

For example, the following configuration adds an admonition with the `custom` keyword. This admonition will be styled as an [Infima `alert-info` component](https://infima.dev/docs/components/alert):
Copy link
Collaborator

Choose a reason for hiding this comment

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

I'd rather not couple this doc to Infima, considering we'll provide themes that are not using Infima in the future.

What you can say is that the admonition will have a .admonition-custom classname that users can target with custom CSS


```js title="docusaurus.config.js"
module.exports = {
// ...
presets: [
[
"@docusaurus/preset-classic",
{
docs: {
// ...
admonitions: {
customTypes: {
custom: {
Copy link
Collaborator

Choose a reason for hiding this comment

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

"custom" may not be the best choice, I'd rather use "admonitionExample"

ifmClass: "info",
Copy link
Collaborator

Choose a reason for hiding this comment

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

Remove infima class

Copy link
Collaborator

Choose a reason for hiding this comment

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

This is directly passed to remark-admonitions. Surprising it may sound, but remark-admonitions is built on top of Infima. I think we should build an unbiased remark plugin using Remark directive ourselves 🤷‍♂️

svg: '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M15 2H1c-.55 0-1 .45-1 1v9c0 .55.45 1 1 1h5.34c-.25.61-.86 1.39-2.34 2h8c-1.48-.61-2.09-1.39-2.34-2H15c.55 0 1-.45 1-1V3c0-.55-.45-1-1-1zm0 9H1V3h14v8z"></path></svg>'
},
},
},
},
}
]
]
};
```

Further documentation is available on [Remark's own repository](https://github.com/elviswolcott/remark-admonitions#custom-types).