自定义 CSS

在主题默认样式之上添加自定义 CSS，以匹配您的品牌或调整特定样式。

添加自定义 CSS

在项目根目录（与 docs.json 同一文件夹）中创建 style.css 文件。Jamdesk 会将其应用于每个页面，无需在 docs.json 中添加任何条目。

项目根目录中的任何 .css 文件均可使用，不限于 style.css。Jamdesk 会按文件名的字母顺序合并多个文件。

运行 jamdesk dev 可在本地预览效果。它渲染自定义 CSS 的方式与已发布的站点一致。

/* Your custom styles */
article h1 {
  font-size: 2.5rem;
}

CSS 和 JS 示例介绍了如何更改页眉颜色以及添加浮动按钮。

CSS 变量

颜色和圆角来自 CSS 变量。在 :root 上覆盖它们，所有使用这些变量的组件都会随之变化：

:root {
  /* Page and text colors */
  --color-bg-primary: #ffffff;      /* page background */
  --color-bg-secondary: #f8fafc;    /* inputs, subtle panels */
  --color-text-primary: #0a0a0a;    /* headings */
  --color-text-secondary: #404144;  /* body text */
  --color-text-muted: #737373;      /* captions and hints */
  --color-border: #e2e8f0;

  /* Corner radius for cards, buttons and panels */
  --radius-sm: 6px;
  --radius-md: 8px;
  --radius-lg: 12px;
}

上述值为 Jam 主题的默认值。其他主题使用各自的初始值。您可以在浏览器开发者工具中查看 <html> 元素上的任意一项。

品牌颜色应配置在 docs.json 中，而非此处。Jamdesk 会将 colors.primary 转换为用于链接、按钮和侧边栏活动项的强调色。参见自定义颜色。

字体同样应配置在 docs.json 中。fonts 字段可加载 Google Font 或您自己的字体文件，并将其应用于所有位置。仅在 CSS 中设置 font-family 需要配合 !important 才能生效，因为主题使用更具体的选择器来设置字体。参见排版。

常见自定义项

更改代码字体

除非使用 !important 覆盖，代码块将保留主题的等宽字体：

@import url('https://fonts.googleapis.com/css2?family=Fira+Code&display=swap');

article pre,
article pre code,
article code {
  font-family: 'Fira Code', monospace !important;
  font-variant-ligatures: common-ligatures;
}

自定义链接样式

页面正文中的链接始终带有类名。请根据其所在位置进行选择，而非使用 a:not([class])：

article .prose a {
  text-decoration: underline;
  text-underline-offset: 3px;
}

article .prose a:hover {
  text-decoration-thickness: 2px;
}

调整标题间距

article .prose h2 {
  margin-top: 3rem;
  margin-bottom: 1rem;
}

article .prose h3 {
  margin-top: 2rem;
  margin-bottom: 0.75rem;
}

设置提示框样式

提示框的颜色来自以 -bg、-border 和 -text 结尾的变量：

/* Warmer Note callouts */
:root {
  --color-note-bg: #fef3c7;
  --color-note-border: #f59e0b;
}

设置当前选中标签页的样式

article [role="tab"][aria-selected="true"] {
  border-bottom-width: 3px;
}

深色模式

Jamdesk 在深色模式下会为 <html> 添加 dark 类。请将深色模式的覆盖样式放在 html.dark 下：

/* Light mode */
:root {
  --color-bg-primary: #fffdf7;
}

.custom-banner {
  background: #f0f4ff;
  color: #1e3a5f;
}

/* Dark mode */
html.dark {
  --color-bg-primary: #14110f;
}

html.dark .custom-banner {
  background: #1e293b;
  color: #e2e8f0;
}

可用选择器

Jamdesk 的类名来自 Tailwind，可能会在任何版本中发生变化。以下钩子是稳定的：

横幅

你在 docs.json 中设置的横幅有自己的稳定钩子：

请在 .jd-banner 上设置颜色变量，而不是在 :root 上。warning 和 danger 类型会在横幅栏上设置自己的值，所以 :root 上的值影响不到它们。

普通的 .jd-banner 规则会改变所有类型的样式：

.jd-banner {
  --jd-banner-bg: #111827;
  --jd-banner-fg: #f9fafb;
}

加上属性选择器，只改变一种类型的样式：

.jd-banner[data-type="danger"] {
  --jd-banner-bg: #7f1d1d;
}

如果你的 CSS 里有类似 [data-jd-banner] { background: ... } 的旧规则，它会改变所有类型的颜色，包括 warning 和 danger。请改用上面的规则之一。

用 --jd-banner-height 让你自己的吸顶元素保持在横幅栏下方。没有横幅显示时不会设置这个变量，所以请给它一个 0px 的后备值：

.my-sticky-toolbar {
  position: sticky;
  top: var(--jd-banner-height, 0px);
}

外部字体

只要可能，请通过 docs.json 加载字体。fonts 字段可加载 Google Font 和自托管字体文件（包括您仓库中的 .woff2 文件），并将其应用于标题和正文。

对于 fonts 未涵盖的内容（例如上文的代码字体，或某个元素上使用的不同字体），可以使用 CSS 作为备选方案。通过 @import 或 @font-face 加载字体，然后使用 !important 进行设置：

@font-face {
  font-family: 'CustomFont';
  src: url('/fonts/custom-font.woff2') format('woff2');
  font-weight: 400;
  font-display: swap;
}

article .prose blockquote {
  font-family: 'CustomFont', serif !important;
}

响应式样式

使用媒体查询来调整不同屏幕尺寸下的样式：

/* Phones */
@media (max-width: 768px) {
  article h1 {
    font-size: 1.75rem;
  }
}

调试

右键点击元素并选择检查，以确定要定位的目标。优先使用推荐使用的选择器、role="tab" 等角色属性以及 CSS 变量，而非冗长的 Tailwind 类名。如果规则未生效，请检查样式面板中是否有主题规则因优先级更高或使用了 !important 而覆盖了您的规则。

限制

• CSS 是全局生效的。请使用具体的选择器以避免冲突
• 部分主题样式（包括字体和 Jam 页眉背景）使用了 !important 或非常具体的选择器。您可能需要使用 !important 来覆盖它们
• 本地预览（jamdesk dev）会在浏览器刷新时应用您 CSS 文件中的修改。已发布的站点会在下次构建时获取更改

接下来做什么？