# Styling

Components come without styles. Import the minidocs default styles and adjust them, or write your own from scratch.

## Using the default styles

Import them once in your layout:

```astro
---
import '@minidocs/astro/styles.css';
---
```

## Content styles

Wrap `<Content />` in the `Prose` component and the rendered Markdown gets full typesetting: headings, paragraphs, lists, links, inline code, code blocks, tables, blockquotes, rules and images.

```astro
<Prose>
  <h1>{entry.data.title}</h1>
  <Content />
</Prose>
```

`Prose` renders an `<article>` with the `md-prose` class, and adding that class to any element works the same.

## Dark mode

Colors in the default styles follow the page’s `color-scheme`. Pages using `Layout.Root` declare `color-scheme: light dark` and follow the system. Without the `Layout` components the page stays light; declare it yourself to support dark mode:

```css
:root {
  color-scheme: light dark;
}
```

On sites with a theme switch, set `color-scheme` to `light` or `dark` when it changes, and the components follow.

### Code blocks

By default Astro highlights code with one theme and writes the colors into the markup, so code blocks do not follow light and dark mode. In your Astro config, set a light and a dark theme and turn off the default colors:

```js
// astro.config.mjs
export default defineConfig({
  markdown: {
    shikiConfig: {
      themes: { light: 'github-light', dark: 'github-dark' },
      defaultColor: false,
    },
  },
});
```

Shiki then outputs only two sets of color variables, `md-prose` picks one by `color-scheme`, and code blocks switch with the rest of the page. With a single theme, code blocks keep that theme’s colors.

## Changing variables

```css
:root {
  --md-color-accent: light-dark(#4338ca, #a5b4fc);
  --md-radius: 0;
}
```

Color variables can take a light and a dark value at once with `light-dark()`.

The default styles are black, white and gray only. Give `--md-color-accent` a color, and the current items in the sidebar and table of contents and the links in your content take that color.

Common variables:

| Variable                                                                         | What it sets                                |
| -------------------------------------------------------------------------------- | ------------------------------------------- |
| `--md-color-accent`                                                              | The color of the current position and links |
| `--md-color-bg`, `--md-color-text`, `--md-color-heading`                         | Background, text and heading colors         |
| `--md-radius`                                                                    | Corner radius                               |
| `--md-font-sans`, `--md-font-mono`                                               | Page font and code font                     |
| `--md-layout-sidebar-width`, `--md-layout-main-width`, `--md-layout-aside-width` | Widths of the three columns                 |

See [Components and Styles](/en/docs/reference/components.md#css-variables) for every variable.

## Choosing style files

`@minidocs/astro/styles.css` holds all the default styles. It is made of one file per component, and you can import only some of them:

```css
@import '@minidocs/astro/styles/base.css'; /* variables, needed by the others */
@import '@minidocs/astro/styles/layout.css';
@import '@minidocs/astro/styles/toc.css';
@import '@minidocs/astro/styles/prose.css';
@import '@minidocs/astro/styles/pager.css';
@import '@minidocs/astro/styles/callout.css';
/* sidebar.css left out: the sidebar has no default look, style it from scratch */
```

| File          | Contents                                                                                     |
| ------------- | -------------------------------------------------------------------------------------------- |
| `base.css`    | All variables. Every other file needs it                                                     |
| `layout.css`  | Page layout, breakpoints, the drawer on narrow screens and the folded table of contents      |
| `sidebar.css` | The look of the sidebar itself: rails, the current item, collapse arrows and the menu button |
| `toc.css`     | Table of contents                                                                            |
| `prose.css`   | Content typesetting                                                                          |
| `pager.css`   | Previous and next links                                                                      |
| `callout.css` | Callouts                                                                                     |

There are three degrees of changing how a component looks:

| How much                     | How                                                       |
| ---------------------------- | --------------------------------------------------------- |
| Colors, font sizes, spacing  | Change variables                                          |
| A few details                | Override a few rules on top of the default styles         |
| A different style altogether | Leave out that component’s file and write it from scratch |

Without a file, its component has no default styles at all, with nothing to undo first. The drawer on narrow screens lives in `layout.css`, so it keeps working when you restyle the sidebar.

## Writing your own styles

The elements every component renders carry fixed classes, and states are attributes.

For example, the `<a>` that `Sidebar.Link` renders has the `md-sidebar-link` class, and the link to the current page has `aria-current="page"`. See [Components and Styles](/en/docs/reference/components.md#classes-and-states) for every class and state.

This adds a line to the left of the current page:

```css
.md-sidebar [aria-current='page'] {
  box-shadow: inset 2px 0 var(--md-color-accent);
}
```

> [!NOTE]
> **No need for higher specificity**
>
> The default styles all sit in `@layer minidocs`. Your plain CSS is outside any layer and always wins.

> [!WARNING]
> **Scoped styles**
>
> Styles in a `<style>` tag of an `.astro` file only apply to that file’s own markup by default, not to elements that minidocs components render. Style those with `<style is:global>` or a separate CSS file.

## With Tailwind

To use the default styles with Tailwind, import them into Tailwind’s `components` layer:

```css
@import 'tailwindcss';
@import '@minidocs/astro/styles.css' layer(components);
```

> [!WARNING]
> **Don’t leave out layer(components)**
>
> Without it, the default styles either override your Tailwind classes or get overridden by Tailwind’s reset, which makes headings in your content as small as body text.

Component states are attributes, so Tailwind’s built-in variants style them:

```astro
<Sidebar.Link {...nav.of(node)} class="aria-[current=page]:font-semibold">
<Sidebar.Group {...nav.of(node)} class="data-[state=open]:bg-zinc-50">
```

The variables of the default styles also work on your own markup, so the rest of the site keeps the same colors as the components and follows dark mode too:

```astro
<header class="border-b border-(--md-color-border) bg-(--md-color-bg)">
```

To use only some of the default styles, add `layer(components)` to each file the same way.

## Without the default styles

Don’t import any style file. The components’ interactions are not affected.