Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
  • Loading branch information
homotechsual committed Aug 3, 2024
2 parents 53929e0 + 10e1357 commit c9ec9eb
Show file tree
Hide file tree
Showing 12 changed files with 277 additions and 2 deletions.
2 changes: 1 addition & 1 deletion docs/deployment/docker/_partials/_dockerfile-pnpm.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ FROM prod as serve
## Expose the port that Docusaurus will run on.
EXPOSE 3000
## Run the production server.
CMD ["pnpm", "serve", "--host", "--", "0.0.0.0", "--no-open"]
CMD ["pnpm", "serve", "--host", "0.0.0.0", "--no-open"]
# Stage 3b: Serve with Caddy.
FROM caddy:2-alpine as caddy
Expand Down
2 changes: 1 addition & 1 deletion docs/deployment/docker/_partials/_dockerfile-yarn.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ FROM prod as serve
## Expose the port that Docusaurus will run on.
EXPOSE 3000
## Run the production server.
CMD ["yarn", "serve", "--host", "--", "0.0.0.0", "--no-open"]
CMD ["yarn", "serve", "--host", "0.0.0.0", "--no-open"]
# Stage 3b: Serve with Caddy.
FROM caddy:2-alpine as caddy
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/design/admonitions/dark-mode-note.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
275 changes: 275 additions & 0 deletions docs/design/admonitions/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,275 @@
---
title: Customising Admonitions
description: A comprehensive guide on how to easily edit admonitions and their appearance.
---

:::success[Beginner Friendly]

This guide is made for beginners, by beginners, aiming to explain how Docusaurus uses HTML
and CSS to create page elements. No prior front-end knowledge is needed!

:::

When working on your Docusaurus project, you may not like the appearance of the default
admonitions... If you are looking to override their color WITHOUT creating a whole new
admonition, then you've come to the right place!

:::info

This page does not cover how to create custom admonitions, only overriding the default
Docusaurus admonition appearance. If you want to create custom admonitions that DON'T interfere with the default
admonitions, we have a guide for that: [Admonitions](/knowledge/component-library/existing/Admonitions/)

:::

## Background Knowledge

If you are unfamiliar with the Docusaurus admonitions and their appearance, visit the Docusaurus
official documentation relating to admonitions by clicking the button below.

<DocusaurusButton
label="Docusaurus Documentation: Admonitions"
to="https://docusaurus.io/docs/markdown-features/admonitions"
/>

To understand how admonitions work, we need to utilize Inspect Element to find things such
as HTML class names and CSS values that the admonitions use.

### Using Inspect Element

The best way to see how admonitions work (if you are using Chrome) is to highlight the title
of the admonition, right-click, and select "Inspect." This will bring up Inspect Element.
Inspect is key to figuring out how to override the appearance of the default admonitions.

:::tip

If you want to make changes to any element of your website but find yourself stuck, Inspect
Element is a powerful tool for making local, temporary changes!

:::

![Use Inspect on the "note" admonition's title](inspect-admonition.png)

From here, we can find the HTML of all the Docusaurus page elements. For this guide, we are only
going to focus on the admonitions.

## Analyzing the HTML (Using Inspect)

When clicking inspect on your site, you may find something like this:

![Inspect Element of a Docusaurus website](inspect-element.png)

Don't be afraid! This is the HTML that Docusaurus generates to make your website!
If you click around in Inspect Element, you will eventually find the elements that
are the admonitions. We can see that the "note" admonition that we highlighted is
an HTML `<div>` element, with a couple of classes attatched to it.

![The "note" admonition's HTML code](note-admonition-html.png)

For our purposes, we are interested in that last class: `alert--secondary`. This is
the driving class that tells the "note" admonition what colors to use. We can find what
variables it uses with Inspect Element as well. Switch to the "Styles" tab in Inspect Element
and use the search bar to find the "note" admonition's class: `alert--secondary`.

## Analyzing the CSS (Using Inspect)

![The "note" admonition's CSS code](note-css.png)

This is the note admonitions CSS code. This is what tells the note admonition what
colors to use. We see four attributes and their corresponding default variables:

### ⭐️ Note admonition's default CSS Values

| CSS Attribute | Default Value |
| ---------------------------------------- | ------------------------------------------------ |
| `--ifm-alert-background-color` | `var(--ifm-color-secondary-contrast-background)` |
| `--ifm-alert-background-color-highlight` | `rgba(235, 237, 240, 0.15)` |
| `--ifm-alert-foreground-color` | `var(--ifm-color-secondary-contrast-foreground)` |
| `--ifm-alert-border-color` | `var(--ifm-color-secondary-dark)` |

![Diagram that points to what each admonition variable corresponds to on an example "note" admonition](admonition-var-diagram.png)

Let's say we want to override the background of the "note" admonition to purple. Well,
we can change the value using Inspect and see the color update in real time. Try changing
the value of `--ifm-alert-background-color` to any color!

:::warning

All changes made using Inspect Element are temporary! Refreshing the page will revert any changes
we made with Inspect.

:::

![Overriding the "note" background color using Inspect Element](overriding-note-bg-color.gif)

## Updating the CSS

Now that we know that the CSS is responsible for the appearance of admonitions, we need to
update the CSS code of our Docusaurus site to override the default values to our new colors.

In your code editor, in the directory of your Docusaurus site, navigate to `src/css/custom.css`.
This is where we can add permanent overrides to the CSS of our site, which means we can update the
colors of our admonitions.

We want to make overrides to the `alert--secondary` (note admonition) class's CSS we found. Add the
`alert--secondary` class to your `custom.css` by copy and pasting the code below into `custom.css`.

```css title="src/css/custom.css"
.alert--secondary {
--ifm-alert-background-color: rgb(237, 219, 255);
--ifm-alert-background-color-highlight: rgb(235, 237, 240);
--ifm-alert-foreground-color: var(--ifm-color-secondary-contrast-foreground);
--ifm-alert-border-color: var(--ifm-color-secondary-dark);
}
```

Now, we can change the variables here to any color we desire! This next code block will override the
"note" admonition's color to an example of colors.

```css title="src/css/custom.css"
.alert--secondary {
--ifm-alert-background-color: rgb(210, 216, 255);
--ifm-alert-background-color-highlight: rgb(233, 187, 255);
--ifm-alert-foreground-color: rgb(216, 36, 111);
--ifm-alert-border-color: rgb(38, 31, 41);
}
```

![The "note" admontion with custom colors](note-custom-colors.png)

:::tip

You can also define colors using hex values!

```css title="src/css/custom.css"
.alert--secondary {
--ifm-alert-background-color: #d2d8ff;
--ifm-alert-background-color-highlight: #e9bbff;
--ifm-alert-foreground-color: #d8246f;
--ifm-alert-border-color: #261f29;
}
```

:::

## ⭐️ Admonition Class Names

Here are the names of all the default admonition classes:

| Admonition | Class Name |
| ---------- | ------------------ |
| Note | `alert--secondary` |
| Tip | `alert--success` |
| Info | `alert--info` |
| Warning | `alert--warning` |
| Danger | `alert--danger` |

You can use these class names in `custom.css` to override their appearance as well, just
like how we did with the "note" admonition.

## Making Color-Responsive Admonitions

You may notice that your new colors might not look good when your Docusaurus site switches
from light mode to dark mode (or vice versa). In order to make our admonitions responsive
to the color mode of our website, we can use custom CSS variables!

### Make a Custom CSS Variable

First, let's make a custom CSS variable that will store any color of our choice.

In your `custom.css`, Docusaurus comes with a `:root` and a `[data-theme='dark']` config by
default. You can name your variable anything you would like, just make sure it is descriptive
and fits your needs!

:::note

It is recommended you add a new config: `[data-theme='light']`, although, it is not
required, and all light mode variables can be put inside of `:root`. The guide will continue with
creating the new config for the light theme.

:::

```css css title="src/css/custom.css"
[data-theme='light'] {
--note-bg: rgb(210, 216, 255);
}
```

### Apply Custom CSS Variable

Now that we created our new color variable `--note-bg`, we have to apply it to the `alert--secondary`
CSS class. Update the static RGB value of `.alert--secondary` to our new variable, using `var()`.

```css title="src/css/custom.css"
.alert--secondary {
// highlight-next-line
--ifm-alert-background-color: var(--note-bg);
--ifm-alert-background-color-highlight: rgb(233, 187, 255);
--ifm-alert-foreground-color: rgb(216, 36, 111);
--ifm-alert-border-color: rgb(38, 31, 41);
}
```

Now, let's add a color for when the page is in dark mode. The procedure is very similar to the
previous steps, excpt we are adding a new variable to the dark mode config!

```css title="src/css/custom.css"
[data-theme='light'] {
--note-bg: rgb(210, 216, 255);
}

[data-theme='dark'] {
--note-bg: rgb(83, 73, 126);
// ...
}
```

Let's go ahead and set the colors of all our other parts of the note admonition. Here's an
example:

```css title="src/css/custom.css"
[data-theme='light'] {
--note-bg: rgb(210, 216, 255);
--note-highlight: rgb(233, 187, 255);
--note-foreground: rgb(216, 36, 111);
--note-border: rgb(38, 31, 41);
}

[data-theme='dark'] {
--note-bg: rgb(83, 73, 126);
--note-highlight: rgb(68, 58, 72);
--note-foreground: rgb(255, 255, 255);
--note-border: rgb(226, 158, 255);
// ...
}

.alert--secondary {
--ifm-alert-background-color: var(--note-bg);
--ifm-alert-background-color-highlight: var(--note-highlight);
--ifm-alert-foreground-color: var(--note-foreground);
--ifm-alert-border-color: var(--note-border);
}
```

### Results

Now we can observe that the colors of our "note" admonition change between light mode and dark
mode!

![Light mode "note" admonition with custom colors](light-mode-note.png)

![Dark mode "note" admonition with custom colors](dark-mode-note.png)

## Conclusion

Congratulations! You are now a pro at overriding the basic colors of the "note" admonition!
Using your knowledge, you should be able to override the colors of all the default admonitions using
the [class names](#%EF%B8%8F-admonition-class-names) listed above!

:::tip

Use your new HTML and CSS knowledge to see what other elements of the webpage you can edit! Find
their class names, and tinker with them in your `custom.css` file, just like how you did with the
"note" admonition!

:::
Binary file added docs/design/admonitions/inspect-admonition.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/design/admonitions/inspect-element.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/design/admonitions/light-mode-note.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/design/admonitions/note-admonition-html.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/design/admonitions/note-css.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/design/admonitions/note-custom-colors.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

1 comment on commit c9ec9eb

@github-actions
Copy link

Choose a reason for hiding this comment

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

⚡ Successfully deployed to Cloudflare Pages!

| 🔨 Latest commit | c9ec9eb |
| 🔍 Latest deploy log | https://github.com/DocusaurusCommunity/website/actions/runs/10229698100 |
| 😎 Deploy preview URL | https://274b1e1b.docusauruscommunitywebsite.pages.dev |
| 🌳 Environment | production |

Please sign in to comment.