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:

---
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.

<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:

: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:

// 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

: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:

See Components and Styles 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:

@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 */

There are three degrees of changing how a component looks:

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 for every class and state.

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

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

With Tailwind

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

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

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

<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:

<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.