# 样式

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

## 使用默认样式

在布局里引入一次：

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

## 正文样式

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

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

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

## 深色模式

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

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

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

### 代码块

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

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

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

## 修改变量

```css
: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` | 三栏的宽度       |

全部变量见[组件与样式](/docs/reference/components.md#css-%E5%8F%98%E9%87%8F)。

## 选择样式文件

`@minidocs/astro/styles.css` 包含了全部默认样式。它由按组件分开的几个文件组成，可以只引入其中一部分：

```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 和状态见[组件与样式](/docs/reference/components.md#class-%E5%92%8C%E7%8A%B6%E6%80%81)。

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

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

> [!NOTE]
> **不需要提高优先级**
>
> 默认样式全部放在 `@layer minidocs` 中。你写的普通 CSS 不在任何 layer 里，总会覆盖它。

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

## 配合 Tailwind

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

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

> [!WARNING]
> **不要漏掉 layer(components)**
>
> 漏掉时，默认样式要么压过你写的 Tailwind 类，要么被 Tailwind 的样式重置压过，比如正文的标题全部变成正文字号。

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

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

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

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

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

## 完全不使用默认样式

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