在博客中使用 March7th UI

March7th UI 基于原生 Web Components，适合在 Astro、Markdown、MDX 或其它内容型站点中直接使用。写文章时可以继续使用 Markdown，只在需要增强表达的位置插入 <m7-*> 标签。

Markdown 负责内容结构，March7th UI 负责提示、步骤、卡片、标签页和状态展示。文章仍然是文章，不需要为了几个交互块改成完整页面开发。

适用场景

  • 教程、项目复盘、更新日志、组件演示等文章需要更清晰的表达层级。
  • 不想在每篇文章里复制 HTML 和 CSS，但希望有统一的提示、步骤、卡片和交互组件。
  • 博客正文主要是 Markdown，只有少量位置需要交互能力。

推荐接入方式

博客正文通常不需要在所有页面都加载组件库。推荐新增一个专门的加载组件，只放在文章阅读页的 <head> 中，并且在 CDN 地址里固定 npm 版本。

---
const packageName = "@mar7th/march7th-ui";
const packageVersion = "1.1.2";
const cdnBase = `https://unpkg.com/${packageName}@${packageVersion}`;
---

<link rel="preconnect" href="https://unpkg.com" crossorigin />
<link rel="stylesheet" href={`${cdnBase}/dist/march7th-tokens.css`} />
<link rel="stylesheet" href={`${cdnBase}/dist/march7th-ui.css`} />
<script is:inline src={`${cdnBase}/dist/march7th-ui.bundle.min.js`} defer></script>

固定版本号可以避免线上文章跟随 latest 自动变化。升级组件库时，手动改版本并验证文章页即可。

在 Astro 文章页引入

以 Astro 博客为例，可以把上面的资源加载逻辑封装成 M7Components.astro，再只在 post 阅读页引入。

---
import M7Components from "@components/misc/M7Components.astro";
---

<MainGridLayout title={entry.data.title} description={entry.data.description}>
  <M7Components slot="head" />

  <Markdown class="markdown-content">
    <Content />
  </Markdown>
</MainGridLayout>

这样组件库只影响文章正文页，首页、归档页、关于页等不需要组件增强的页面不会额外加载资源。

同步博客主题

如果博客本身已经有亮暗模式和主题色，需要把这些状态同步给 March7th UI。最少要同步 m7-dark 类、--m7-hue 变量和当前解析后的模式。

<script is:inline>
  const root = document.documentElement;

  function syncM7Theme() {
    const isDark = root.classList.contains("dark");
    const hue = getComputedStyle(root).getPropertyValue("--hue").trim() || "215";

    root.classList.toggle("m7-dark", isDark);
    root.style.setProperty("--m7-hue", hue);
    root.setAttribute("data-m7-resolved-mode", isDark ? "dark" : "light");
  }

  syncM7Theme();
  new MutationObserver(syncM7Theme).observe(root, {
    attributes: true,
    attributeFilter: ["class", "style"]
  });
</script>
不要只加载脚本而忽略主题同步。否则正文已经切到暗色时，组件可能仍按亮色变量显示，视觉上会割裂。

在 Markdown 中书写

普通 Markdown 可以保留原始 HTML，因此可以直接写小写短横线形式的自定义标签。MDX 中同样可以使用 <m7-button> 这类标签，不需要 import。

发布文章 保存草稿 Markdown Web Components 
<m7-button type="primary">发布文章</m7-button>
<m7-button>保存草稿</m7-button>
<m7-badge type="success">Markdown</m7-badge>
<m7-badge type="info">Web Components</m7-badge>
组件适合强调重点、拆分步骤和展示状态，不建议替代正文解释。
适合日常博客、教程、笔记和长文，写作成本最低。
适合混入框架组件或运行时代码，能力更强但复杂度更高。
适合补充交互表达，写法接近 HTML，维护集中在组件库。
 
<m7-notice type="note" title="写作提示">
  组件适合强调重点、拆分步骤和展示状态，不建议替代正文解释。
</m7-notice>

<m7-tabs active="0">
  <section label="Markdown">适合日常博客、教程、笔记和长文。</section>
  <section label="MDX">适合混入框架组件或运行时代码。</section>
  <section label="m7 组件">适合补充交互表达。</section>
</m7-tabs>

按需与自托管

CDN 全量 bundle 最适合快速接入和验证。如果文章长期只使用少数组件，可以使用 自定义软件包 生成更小的脚本，或把 dist 文件放进博客的 public 目录自托管。

方式适合场景取舍
固定版本 CDN快速接入、方便升级验证依赖 CDN 网络
自托管 dist 文件希望资源完全由站点控制需要手动同步版本
Builder 定制包文章只用固定少数组件升级时需要重新生成

写作建议

  • 组件用于增强重点表达，不要把整篇文章写成组件堆叠。
  • 先同步主题变量，再评估页面圆角、背景、文字和卡片层级是否一致。
  • 在文章中优先使用提示、步骤、标签页、折叠面板、徽章、统计卡片这类阅读型组件。
  • 如果需要复杂运行时逻辑，再考虑 MDX 或框架组件；普通展示内容用 Markdown 加 m7 标签即可。