自定义扩展

ModernDuang 主题提供了丰富的配置选项，但如果你需要更深层次的定制，可以通过以下方式扩展主题功能。

重要提示： 建议优先使用 _config.modernduang.yml 进行所有可配置的调整，避免直接修改主题源文件，这样在更新主题时不会丢失你的自定义内容。

覆盖 CSS 变量

ModernDuang 使用 CSS 自定义属性（变量）来控制颜色、间距、阴影等视觉属性。你可以在 source/css/main.css 中覆盖这些变量来定制外观。

常用 CSS 变量

以下是主题中所有的 CSS 变量及其默认值：

:root {
  /* 主题色 */
  --primary: #4F46E5;           /* 主题色（靛蓝） */
  --primary-light: #818CF8;     /* 浅主题色 */
  --secondary: #818CF8;         /* 辅助色 */
  --cta: #F97316;               /* 强调/CTA 色（橙色） */
  --cta-hover: #EA580C;         /* CTA 悬停色 */

  /* 背景 */
  --bg-main: #EEF2FF;           /* 主背景色 */
  --bg-card: #FFFFFF;           /* 卡片背景色 */
  --bg-elevated: #F8FAFF;       /* 浮层背景色 */

  /* 文字 */
  --text-primary: #1E1B4B;      /* 主文字色 */
  --text-secondary: #4B5563;    /* 次文字色 */
  --text-muted: #9CA3AF;        /* 弱化文字色 */

  /* 柔和粉彩 */
  --pastel-pink: #FDBCB4;
  --pastel-blue: #ADD8E6;
  --pastel-mint: #98FF98;
  --pastel-lilac: #E6E6FA;
  --pastel-yellow: #FFFACD;

  /* 粘土阴影 */
  --shadow-clay: inset -2px -2px 8px rgba(255,255,255,0.8),
                 inset 2px 2px 8px rgba(0,0,0,0.1),
                 4px 4px 12px rgba(79,70,229,0.15);
  --shadow-clay-hover: inset -2px -2px 8px rgba(255,255,255,0.9),
                       inset 2px 2px 8px rgba(0,0,0,0.08),
                       6px 6px 20px rgba(79,70,229,0.2);
  --shadow-pressed: inset 2px 2px 8px rgba(0,0,0,0.15),
                    inset -2px -2px 8px rgba(255,255,255,0.5);

  /* 圆角 */
  --radius-sm: 12px;
  --radius-md: 16px;
  --radius-lg: 24px;
  --radius-xl: 32px;
  --radius-pill: 9999px;

  /* 字体 */
  --font-display: 'Fredoka', 'Nunito', sans-serif;
  --font-body: 'Nunito', -apple-system, sans-serif;
  --font-mono: 'JetBrains Mono', 'SF Mono', Monaco, Consolas, monospace;

  /* 边框与状态色 */
  --border: #E5E7EB;
  --success: #22c55e;
  --warning: #d97706;
  --declare: #8b5cf6;
  --danger: #dc2626;

  /* 间距 */
  --spacing-xs: 8px;
  --spacing-sm: 12px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
  --spacing-xxl: 48px;
  --spacing-section: 96px;
}

暗色模式变量

[data-theme="dark"] {
  --bg-main: #0f172a;
  --bg-card: #1e293b;
  --bg-elevated: #334155;
  --text-primary: #f1f5f9;
  --text-secondary: #cbd5e1;
  --text-muted: #64748b;
  --pastel-pink: #4c1d36;
  --pastel-blue: #1e3a5f;
  --pastel-mint: #1a3a2a;
  --pastel-lilac: #2d2047;
  --pastel-yellow: #3d3520;
  --shadow-clay: inset -2px -2px 8px rgba(255,255,255,0.05),
                 inset 2px 2px 8px rgba(0,0,0,0.3),
                 4px 4px 12px rgba(0,0,0,0.4);
  --shadow-clay-hover: inset -2px -2px 8px rgba(255,255,255,0.08),
                       inset 2px 2px 8px rgba(0,0,0,0.2),
                       6px 6px 20px rgba(0,0,0,0.5);
}

如何覆盖

编辑 source/css/main.css，在文件末尾添加你的自定义样式：

/* 自定义主题色 */
:root {
  --primary: #E8A0BF;
  --primary-light: #F2C4D5;
  --cta: #E8785A;
}

/* 自定义暗色模式 */
[data-theme="dark"] {
  --bg-main: #1a1a2e;
  --bg-card: #16213e;
  --text-primary: #eaeaea;
}

/* 调整卡片阴影 */
.post-card {
  box-shadow: var(--shadow-clay);
  border-radius: var(--radius-lg);
}

自定义 JavaScript

你可以在 source/js/main.js 中添加自定义 JavaScript 代码，用于实现额外的交互功能。

// 自定义 JavaScript
document.addEventListener('DOMContentLoaded', function() {
  // 你的自定义代码
  console.log('博客已加载！');

  // 例如：为所有外部链接添加 target="_blank"
  document.querySelectorAll('a[href^="http"]').forEach(link => {
    if (!link.href.includes(window.location.hostname)) {
      link.setAttribute('target', '_blank');
      link.setAttribute('rel', 'noopener noreferrer');
    }
  });
});

修改布局模板

主题的布局模板位于 layout/ 目录中，使用 EJS 模板引擎。你可以修改这些文件来调整页面的 HTML 结构。

主要模板文件

文件	用途
`layout/layout.ejs`	基础布局（包含 HTML 头部、导航、页脚）
`layout/index.ejs`	首页模板
`layout/post.ejs`	文章详情页模板
`layout/archive.ejs`	归档页模板
`layout/tags.ejs`	标签页模板
`layout/categories.ejs`	分类页模板
`layout/links.ejs`	友链页模板
`layout/partials/header.ejs`	头部导航组件
`layout/partials/footer.ejs`	页脚组件
`layout/partials/comments.ejs`	评论组件

示例：在头部添加自定义 meta 标签

编辑 layout/partials/header.ejs，在 <head> 标签内添加：

<!-- 自定义 meta 标签 -->
<meta name="theme-color" content="#6C9BCF">
<meta name="msapplication-TileColor" content="#6C9BCF">

示例：在页脚注入统计代码

编辑 layout/partials/footer.ejs，在 </body> 前添加：

<!-- Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

自定义友链申请内容

ModernDuang 的友链页面包含一个「友链申请」区块，内容由 layout/_link-apply.md 文件控制。这个文件使用标准 Markdown 语法，并结合主题提供的特殊语法来展示你的站点信息。

申请模板结构

板块的标题通过文件顶部的 frontmatter 配置，正文使用标准 Markdown 语法：

---
title: 交换友链
---

欢迎交换友链！在添加之前请先阅读以下信息。

### 我的站点

<!-- siteinfo -->

### 申请条件

1. 站点内容健康、积极向上
2. 定期更新，无大量死链
3. 已添加本站友链

### 申请格式

请在下方评论区按以下格式留言：

{%card%}
名称: 你的站点名称
URL: https://yourblog.com
描述: 简短描述（20字以内）
头像: https://yourblog.com/avatar.png
分组: 朋友们
{%card%}

`{%card%}` 块

{%card%}内容{%card%} 将内容包裹在粘土风格的卡片容器中，用于突出显示你的站点信息。注意开始和结束使用相同的标签。

`` 占位符

 是一个特殊占位符，会自动替换为你的站点信息表格：

属性	来源
站点名称	Hexo `_config.yml` 中的 `title`
站点描述	Hexo `_config.yml` 中的 `description`
站点 URL	`_config.modernduang.yml` 中的 `siteInfo.url`
头像	`_config.modernduang.yml` 中的 `siteInfo.avatar`
Atom 订阅	`_config.modernduang.yml` 中的 `siteInfo.atom`

自定义申请文案

你可以自由编辑 layout/_link-apply.md，使用任意标准 Markdown 语法。只需要保留 {%card%} 块和  占位符来展示站点信息，其余部分可以完全自定义。

自定义 404 页面

ModernDuang 内置了一个美观的 404 页面。如需自定义，复制并修改主题中的 404 页面模板：

cp themes/modernduang/layout/404.ejs layout/404.ejs

然后编辑 layout/404.ejs 文件，自定义页面内容：

<section class="error-section">
  <div class="error-content">
    <!-- 请在 error-content 容器内编写代码 -->
    <h1>404</h1>
    <p>抱歉，你访问的页面不存在。</p>
    <p>可能是链接已失效，或者你输入了错误的地址。</p>
    <a href="<%= url_for('/') %>">返回首页</a>
  </div>
</section>

添加自定义字体

方法一：通过配置文件添加 Google Fonts

在 _config.modernduang.yml 中配置 font 选项：

font:
  enable: true
  host: https://fonts.googleapis.com
  global:
    external: true
    families:
      - Playfair+Display:ital,wght@0,400;0,500;0,600;0,700;1,400
      - Inter:wght@300;400;500;600
      - JetBrains+Mono:wght@400;500
      - Noto+Sans+SC:wght@400;500;700   # 添加中文字体

国内用户提示： 如果 Google Fonts 加载缓慢，可将 font.host 改为国内镜像站，例如 https://fonts.googleapis.cn 或 https://fonts.loli.net。

方法二：通过 CSS 引入本地字体

编辑 source/css/main.css，使用 @font-face 引入本地字体：

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

body {
  font-family: 'CustomFont', var(--font-family);
}

将字体文件放在 Hexo 站点的 source/fonts/ 目录下即可。

添加自定义脚本

统计分析脚本

如果你需要使用百度统计、Google Analytics 等第三方统计服务，可以通过页脚的 custom 字段注入单行脚本：

footer:
  custom: '<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>'

对于包含多行代码的复杂脚本（如百度统计、Google Analytics），建议通过 EJS 模板注入，详见上方「修改布局模板」章节中的示例：在页脚注入统计代码。

如果需要在 <head> 中注入脚本（而非页脚），可以编辑 layout/partials/header.ejs，在 <head> 标签内添加你的脚本标签。

主题脚本工作原理

ModernDuang 主题在 scripts/ 目录中包含多个 Hexo 辅助脚本，用于扩展 Hexo 的生成能力。你可以在 Hexo 站点的 scripts/ 目录下创建自己的脚本来添加新功能。

内置脚本

脚本文件	功能
`scripts/mermaid.js`	为 Markdown 中的 Mermaid 代码块注入渲染脚本和样式
`scripts/note-tags.js`	注册自定义的引用块标签（`{% note %}`、`{% warning %}`、`{% declare %}`、`{% danger %}`）
`scripts/link-apply.js`	处理友链申请页面的 `{%card%}` 块和 `<!-- siteinfo -->` 占位符

`mermaid.js` 工作原理

该脚本在 Hexo 生成过程中检测页面 Front Matter 中的 mermaid: true 标记。当检测到时，它会在页面底部注入 Mermaid 的 CDN 脚本和初始化代码：

// 简化原理示意
hexo.extend.filter.register('after_post_render', function(data) {
  if (data.mermaid) {
    // 注入 mermaid.min.js CDN 脚本
    // 添加 mermaid.initialize() 初始化代码
  }
  return data;
});

`note-tags.js` 工作原理

该脚本注册了一系列 Hexo 标签插件，用于在 Markdown 中创建特殊样式的引用块：

{% note %}
这是一个普通注释
{% endnote %}

{% declare %}
这是一个声明信息
{% enddeclare %}

{% warning %}
这是一个警告信息
{% endwarning %}

{% danger %}
这是一个危险提示
{% enddanger %}

每个标签会被渲染为带有不同颜色和图标的自定义 HTML 块。

`link-apply.js` 工作原理

该脚本处理友链页面的两个特殊语法：

{%card%} 块： 将内容包裹在粘土风格的卡片容器中
 占位符： 替换为从 _config.modernduang.yml 的 siteInfo 配置项中读取的站点信息表格

添加自定义脚本

在 Hexo 站点的 scripts/ 目录下创建 .js 文件，Hexo 会在启动时自动加载这些脚本。例如，创建一个自动为所有外部链接添加 target="_blank" 的脚本：

// scripts/external-link.js
hexo.extend.filter.register('after_post_render', function(data) {
  data.content = data.content.replace(
    /<a href="(https?:\/\/[^"]+)"/g,
    '<a href="$1" target="_blank" rel="noopener noreferrer"'
  );
  return data;
});

最佳实践

优先使用配置文件 — _config.modernduang.yml 覆盖了绝大部分常用设置，优先通过配置文件调整，而非直接修改主题代码。
利用 source 目录 — 将自定义 CSS 和 JS 写在 source/css/main.css 和 source/js/main.js 中，而不是修改主题的源文件。
使用 Hexo scripts 扩展 — 对于需要自定义生成逻辑的场景，在站点 scripts/ 目录下创建脚本，而不是修改主题的 scripts/ 目录。
版本控制自定义内容 — 将你的自定义配置文件、CSS、JS 和脚本纳入 Git 管理，确保自定义内容不会丢失。
关注主题更新日志 — 在更新主题前查看更新日志，了解是否有破坏性变更影响你的自定义内容。

#自定义扩展

#覆盖 CSS 变量

#常用 CSS 变量

#暗色模式变量

#如何覆盖

#自定义 JavaScript

#修改布局模板

#主要模板文件

#示例：在头部添加自定义 meta 标签

#示例：在页脚注入统计代码

#自定义友链申请内容

#申请模板结构

#{%card%} 块

# 占位符

#自定义申请文案

#自定义 404 页面

#添加自定义字体

#方法一：通过配置文件添加 Google Fonts

#方法二：通过 CSS 引入本地字体

#添加自定义脚本

#统计分析脚本

#主题脚本工作原理

#内置脚本

#mermaid.js 工作原理

#note-tags.js 工作原理

#link-apply.js 工作原理

#添加自定义脚本

#最佳实践

#相关页面

自定义扩展

覆盖 CSS 变量

常用 CSS 变量

暗色模式变量

如何覆盖

自定义 JavaScript

修改布局模板

主要模板文件

示例：在头部添加自定义 meta 标签

示例：在页脚注入统计代码

自定义友链申请内容

申请模板结构

`{%card%}` 块

`` 占位符

自定义申请文案

自定义 404 页面

添加自定义字体

方法一：通过配置文件添加 Google Fonts

方法二：通过 CSS 引入本地字体

添加自定义脚本

统计分析脚本

主题脚本工作原理

内置脚本

`mermaid.js` 工作原理

`note-tags.js` 工作原理

`link-apply.js` 工作原理

添加自定义脚本

最佳实践

相关页面