docs: add documentation for custom admonitions #5625
Conversation
Hello, I found myself needing to add a custom admonition, and thought it would be worth adding documentation on how to do so. I've considered adding the admonition itself to this repository to be able to preview it in the docs, but I didn't want to propose a config change unless you agree beforehand.
essential-randomness
requested review from
lex111 and
slorber
as code owners
|
Thank you for your pull request and welcome to our community. Action RequiredIn order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you. ProcessIn order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA. Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks! |
|
✔️ [V2] 🔨 Explore the source changes: e70ade3 🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/615392f7d832dc0007db04a2 😎 Browse the preview: https://deploy-preview-5625--docusaurus-2.netlify.app |
|
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-5625--docusaurus-2.netlify.app/ |
|
|
||
| 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): |
There was a problem hiding this comment.
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
| // ... | ||
| admonitions: { | ||
| customTypes: { | ||
| custom: { |
There was a problem hiding this comment.
"custom" may not be the best choice, I'd rather use "admonitionExample"
| admonitions: { | ||
| customTypes: { | ||
| custom: { | ||
| ifmClass: "info", |
There was a problem hiding this comment.
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 🤷♂️
|
Hi @essential-randomness, please sign the CLA so your PR can be a merge candidate. Your PR has almost gone stale, but if you sign the CLA, I can help you complete it. |
Josh-Cena
added
the
pr: documentation
|
Hi! I need an answer from the Facebook team before signing the CLA since I have some concerns about who has access to my information. I sent the email a month ago now, but haven't gotten a reply. I'll ping them now. If anyone knows where to find the info, I'd love to get us all unblocked. |
|
Okay, I see. Unfortunate that it's been so long, wonder if they would ever respond🙄 It's good to be vigilant. There are a lot of PRs far staler than this so we wouldn't mind waiting, but just pinging to check if everything's up-to-date. |
|
Hey I'm going to close because I'm not sure you'll get a response for the CLA 😅 and I don't feel like it's a good idea to document this. When migrating to MDX 2, we'll likely replace that admonition plugin, so doing what you suggest will be a breaking change that we probably don't want to encourage in the meantime (see #5848 (comment)) |
Motivation
I found myself needing to add a custom admonition, and thought it would be worth adding documentation on how to do so.
I've considered adding the admonition itself to this repository to be able to preview it in the docs, but I didn't want to propose a config change unless you agree beforehand.
Have you read the Contributing Guidelines on pull requests?
Yes.
(Unfortunately, I didn't do so before committing the change, and I'm uncertain how to change the commit message to adhere to the Semantic Commit Messages.)
Test Plan
No code change.
Related PRs
None.