docmd 0.7.6 版本引入了 统一 URL 规范化引擎，消除了 301 重定向，强制执行用于 SEO 的尾随斜杠 URL，并在每个层面带来了始终如一的链接处理。

✨ 特性亮点

统一 URL 规范化

现在所有 URL 处理都通过 @docmd/parser 中的单个 resolveHref() 函数进行。尾随斜杠强制执行、index.md 剥离和双斜杠防止一致地应用于 Markdown 链接、按钮容器、导航和菜单栏。

• 消除 301 重定向: 像 /configuration/overview 这样的 URL 直接在构建时解析为 /configuration/overview/。
• 无路径残留: 在任何渲染的链接中不再有 /index 残留或 .md 扩展名。
• Hreflang 准确性: 备用标签现在可以正确地从页面路径中剥离语言环境前缀。

请参阅 链接与引用 指南以获取完整的 URL 转换表。

通用的 external: 和 raw: 前缀

我们引入了两个新的魔法前缀，让你能够完全控制所有 docmd 组件中的链接行为。

• external: — 强制新标签页打开: 在任何链接（Markdown、按钮、菜单栏）中添加此前缀，以强制其在新标签页中打开。
• raw: — 绕过规范化: 当你需要链接到一个原始的 .md 文件而不希望引擎剥离其扩展名时，请使用此前缀。

[在新标签页中打开](external:./configuration/overview.md)
::: button "API 文档" external:./api/node-api.md
[下载模板](raw:templates/starter.md)

行为变更: HTTP/HTTPS 链接不再自动在新标签页中打开。当你需要该行为时，请显式使用 external:。

插件的集中式 URL API

@docmd/parser 中新的 URL 工具层通过 @docmd/api 重新导出。插件不再需要手动解析 outputPath —— 引擎会为每个页面预先计算纯净的 URL：

import { outputPathToSlug, sanitizeUrl } from '@docmd/api';

export async function onPostBuild({ pages }) {
  for (const page of pages) {
    page.urls.slug;      // "guide/"
    page.urls.canonical; // "https://example.com/guide/"
    page.urls.pathname;  // "/guide/"
  }
}

请参阅 插件开发 指南以获取完整的 API 参考。

🔧 开发者体验

静默插件警告

以前，缺失或配置错误的插件会在 docmd dev 期间的 每次文件更改 时打印警告。现在，插件警告在每个开发会话中 仅打印一次，并在随后的重建中被抑制，以保持终端整洁。

↻ Change in docs/en/guide.md... ⚠️  Could not load plugin: @docmd/plugin-math
Done.

SPA 哈希导航修复

在 SPA 模式下，单击当前页面上的 #heading 锚点现在会平滑地滚动到目标元素。通过哈希历史记录进行的浏览器后退/前进（通过 popstate）也能正确滚动。

[跳转到配置](#configuration)  <!-- 现在在 SPA 模式下可以工作 -->

🚀 SEO 改进

• 尾随斜杠: 所有内部 URL 渲染时带有尾随斜杠，以消除 301 重定向链。
• 纯净路径: 规范链接和 hreflang <link> 标签使用正确的规范化路径。
• 零残留: 生产环境 HTML 中无 .md 扩展名或 /index 片段。

迁移指南

使用 npm update @docmd/core 或 pnpm update @docmd/core 更新。无需更改配置。