样式

组件本身不带样式。你可以引入 minidocs 的默认样式，在它的基础上调整，也可以完全自己写。

使用默认样式

在布局里引入一次：

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

正文样式

用 Prose 组件包住 <Content />，渲染出来的 Markdown 就有了完整的排版：标题、段落、列表、链接、行内代码、代码块、表格、引用、分隔线和图片。

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

Prose 渲染一个带 md-prose class 的 <article>，给任意元素加上这个 class 也一样。

深色模式

默认样式的颜色跟随页面的 color-scheme。用了 Layout.Root 的页面会声明 color-scheme: light dark，跟随系统切换深浅色。不用 Layout 组件时，页面始终是浅色，要支持深色模式就自己声明：

:root {
  color-scheme: light dark;
}

有深浅色切换按钮的站点，切换时把 color-scheme 设成 light 或 dark，组件会跟着变。

代码块

Astro 默认用单一主题高亮代码，颜色直接写在标签上，不会跟随深浅色。在 Astro 配置里同时指定浅色和深色两个主题，并关闭默认颜色：

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

这样 Shiki 只输出两套颜色变量，md-prose 会按 color-scheme 选择其中一套，代码块就和页面的其他部分一起切换。只用单一主题时，代码块保持主题本身的颜色。

修改变量

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

颜色变量可以用 light-dark() 同时给出浅色和深色的值。

默认样式只有黑白灰。给 --md-color-accent 设一个颜色，侧边栏和目录的当前项、正文链接都会换成这个颜色。

常用的变量：

变量	作用
`--md-color-accent`	当前位置和链接的颜色
`--md-color-bg`、`--md-color-text`、`--md-color-heading`	背景、正文和标题的颜色
`--md-radius`	圆角
`--md-font-sans`、`--md-font-mono`	页面字体和代码字体
`--md-layout-sidebar-width`、`--md-layout-main-width`、`--md-layout-aside-width`	三栏的宽度

全部变量见组件与样式。

选择样式文件

@minidocs/astro/styles.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 */

文件	内容
`base.css`	所有变量。其他文件都依赖它
`layout.css`	页面布局、断点、窄屏抽屉、目录的折叠形态
`sidebar.css`	侧边栏本身的外观：导轨、当前项、折叠箭头、菜单按钮
`toc.css`	目录
`prose.css`	正文排版
`pager.css`	翻页
`callout.css`	提示框

改一个组件的外观有三种程度：

想改多少	做法
换颜色、字号、间距	改变量
微调几处	在默认样式上覆盖几条规则
完全换一种风格	不引入这个组件的文件，从零写

不引入某个文件，那个组件就没有任何默认样式，不需要先抵消什么。窄屏下的抽屉在 layout.css 里，所以重写侧边栏的外观时，抽屉照样有效。

自己写样式

每个组件渲染出的元素都带着固定的 class，状态用属性表示。

比如 Sidebar.Link 渲染出的 <a> 带着 md-sidebar-link，当前页面的链接带着 aria-current="page"。所有的 class 和状态见组件与样式。

下面给当前页面加一条左侧竖线：

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

不需要提高优先级

默认样式全部放在 @layer minidocs 中。你写的普通 CSS 不在任何 layer 里，总会覆盖它。

作用域样式

写在 .astro 文件 <style> 里的样式默认只作用于这个文件自己的标签，管不到 minidocs 组件渲染出的元素。给它们写样式时，用 <style is:global> 或者单独的 CSS 文件。

配合 Tailwind

和 Tailwind 一起使用默认样式时，要把默认样式引入到 Tailwind 的 components layer 里：

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

不要漏掉 layer(components)

漏掉时，默认样式要么压过你写的 Tailwind 类，要么被 Tailwind 的样式重置压过，比如正文的标题全部变成正文字号。

组件的状态都是属性，用 Tailwind 自带的变体就能写样式：

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

默认样式的变量也可以直接用在你自己的标签上，这样站点的其他部分会和组件保持一致的配色，深色模式也跟着切换：

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

只想用一部分默认样式时，每个文件都同样加上 layer(components)。

完全不使用默认样式

不引入任何样式文件即可，组件的交互不受影响。