Quartz Style Guide

Purpose

这篇页面是本站的 样式 Demo + 使用手册 + Changelog。后续写文章时优先复用这里的结构，让文本、布局、图片、Callout、导航卡片和流程图保持统一。

适用范围：

长文教程：用目录、Callout、流程步骤和表格组织信息。
技术方案：用双栏、信息框、架构图、对比表和决策块表达取舍。
Wiki 笔记：用统一的链接、引用、图片标题和元信息提升可读性。
首页/专题页：用 Gallery Card、Home Layout 和 Process Steps 做导航。

Style System Map

当前样式入口在 Quartz MKD 和 quartz/styles/custom.scss，主要由 Quartz 官方基础样式和自定义模块组成。

样式模块	文件	用途
Base Typography	`quartz/styles/base.scss`	标题、正文、链接、表格、代码块、布局基础
Callouts	`quartz/styles/callouts.scss`	官方 Callout 颜色、折叠、标题和内容结构
Callout Adjustments	`quartz/styles/custom/callout-adjustments.scss`	Callout 宽度、位置、标题、边框和文本控制
Column Callout	`quartz/styles/custom/column-callout.scss`	用 Callout 组织 2/3 列内容
Caption Callout	`quartz/styles/custom/caption-callout.scss`	图片说明和小型图注
Infobox Callout	`quartz/styles/custom/infobox-callout.scss`	类 Wiki 右侧信息框
Home Layout	`quartz/styles/custom/home-layout.scss`	首页 banner、双栏导航和分区标题
Gallery Card View	`quartz/styles/custom/gallery-card-view.scss`	文章内卡片导航
Process Steps	`quartz/styles/custom/process-steps.scss`	步骤式流程面板
Quote Tabs	`quartz/styles/custom/quote-tabs.scss`	Radio tab 切换式引用面板
Image Layouts	`quartz/styles/images-layouts.scss`	图片卡片、宽图、浮动图、拼贴图
Diagram Components	`quartz/styles/custom/diagram-components.scss`	架构图、流程图、能力地图和决策图

Writing Defaults

Text

一级标题用于页面主题，正文内从 ## 开始组织。
段落保持短句和短段，技术文章每段只表达一个判断。
链接优先使用 Obsidian 双链，例如 Bigdata Wiki OS、Data Architecture。
行内代码用于字段、命令、文件名、参数，例如 dcmm_domain、npm run quartz build。

Tables

表格适合用于能力矩阵、方案对比、字段说明和 Changelog。

场景	推荐结构	示例
工具对比	维度 / 方案 A / 方案 B / 结论	Doris vs StarRocks
治理清单	能力项 / 规则 / 证据 / 责任人	数据质量规则
样式记录	日期 / 变更 / 文件 / 影响	本页 Changelog

Callout Patterns

基础 Callout

Info

用于解释背景、概念补充和上下文说明。本站 Callout 使用左边框和轻背景，适合长文中的信息分层。

Tip

用于最佳实践、写作建议和可复用经验。

Warning

用于风险、限制、兼容性问题和容易误用的样式。

Example

用于展示模板、语法片段和使用案例。

> [!tip]
> 
> 这里写建议内容。

Callout Metadata

自定义 metadata 可以控制位置、宽度、标题、边框和文本。

Metadata	效果	推荐场景
`left` / `right`	左/右浮动	小图注、旁注
`center`	居中	重点说明
`wsmall` / `wmed` / `wtall`	百分比宽度	控制 Callout 宽度
`static`	使用固定像素宽度	需要稳定宽度的示意块
`no-title` / `no-t`	隐藏标题	嵌入式说明
`no-icon` / `no-i`	隐藏图标	更简洁的正文提示
`clean`	移除边框和背景	卡片内嵌、图文组合
`txt-c` / `ttl-c`	内容/标题居中	标语、指标块

> [!info|right wsmall]
> 
> 右侧小型补充说明。

Info

这是一个右侧浮动小提示。移动端会自动变成全宽，避免正文挤压。

正文继续流动时，浮动 Callout 会让短补充更像边注。长内容不建议浮动，应保持全宽。

Info

clear 用于结束浮动影响，让后续内容重新占满正文宽度。

Column Callout

用于把同一层级的观点、方案或能力项并列展示。适合“概念 / 实践 / 产出”这类结构。

Column

Concept

解释核心概念和边界，避免长篇堆叠。

Practice

写商业落地、工具组合和工程实施方式。

Output

明确最后能产出什么文档、图、脚本或检查清单。

> [!column|3 clean]
> 
>
> > [!tip] Concept
> > 内容
>
> > [!example] Practice
> > 内容
>
> > [!summary] Output
> > 内容

Caption Callout

用于图片下方的轻量说明。适合技术架构图、截图、数据图和产品图。

> [!caption]
> 
>
> ![[image.png|wsmall]]
>
> 图片说明。

Infobox

用于文章开头的右侧摘要信息。适合技术组件、项目案例、标准规范和工具介绍。

Infobox

Style Token

Meta

Item Value
Type Guide
Status Active
Owner Wiki

Item	Value
Type	Guide
Status	Active
Owner	Wiki

> [!infobox]
> 
>
> ## Article Title
>
> ### Meta
>
> | Item | Value |
> | --- | --- |
> | Status | Draft |

Gallery Card View

用于专题页或长文开头的导航卡片。卡片有 hover 状态和右侧箭头，适合引导读者跳转。

<nav class="gallery-card-view" aria-label="Featured links">
  <a class="gallery-card internal" href="/index/Data%20Architecture/Bigdata%20Wiki%20OS">
    <span class="gallery-card-title">Bigdata Wiki OS</span>
    <span class="gallery-card-subtitle">Knowledge graph and wiki operating system</span>
  </a>
</nav>

Process Steps

用于展示流程、方法论、实施路线和运维步骤。

Article Styling Workflow

1

Choose the article type

先判断文章是概念卡、架构方案、项目案例、教程还是 Changelog。
2

Apply the structure

用标题、Callout、表格、图和卡片把内容分层，不依赖大段文字硬堆。
3

Verify in Quartz

运行 npm run quartz build，确认 Markdown、Mermaid 和 HTML 片段能被正确解析。

Quote Tabs

Quote Tabs 适合在专题页中对比不同角色视角。目前样式绑定了三个固定 id：qt-cursor、qt-lovable、qt-cognition。如果未来要支持更多 tab，需要扩展 quote-tabs.scss。

Engineer Architect CDO

工程师视角关注代码块、步骤、故障排查和可执行命令。

Use process steps and warning callouts.

架构师视角关注边界、组件关系、取舍和演进路线。

Use diagrams, tables and decision callouts.

CDO 视角关注业务价值、风险控制、指标和组织协同。

Use value maps and governance checklists.

Image Layouts

图片布局建议按用途选择，不要随意混用。

用途	Class / 写法	说明
普通图片	`![[image.png]]`	默认圆角、最大宽度自适应
控制尺寸	`![[image.png\|wsmall]]`	使用 alt metadata 控制宽度
居中图	`![[image.png\|center wmed]]`	适合架构图
右浮动图	`![[image.png\|right wsmall]]`	适合人物、产品截图、小图
宽幅图	`.image-layout-bleed`	适合视觉主图或大图
图片卡片	`.image-layout-card`	适合多图对比
拼贴图	`.image-layout-mosaic`	适合图库或作品集

<figure class="image-layout-feature is-contained">
  <img src="/static/example.png" alt="Architecture diagram">
  <figcaption>架构图说明。</figcaption>
</figure>

Home Layout

首页样式使用 .home-two-col-section、.home-col-left、.home-col-right 和 .home-col-title。适合首页或专题索引，不建议在普通文章中大量使用。

<div class="home-two-col-section">
  <div class="home-col-left">
    <h3 class="home-col-title">Architecture</h3>
    <ul>
      <li>[[Data Architecture]]</li>
      <li>[[Lakehouse]]</li>
    </ul>
  </div>
  <div class="home-col-right">
    <h3 class="home-col-title">AI</h3>
    <ul>
      <li>[[Data Agent Architecture]]</li>
      <li>[[RAG]]</li>
    </ul>
  </div>
</div>

Diagram Components

当 Mermaid 不够美观，优先使用 Quartz Diagram Style Guide 中的 wiki-diagram-* 组件。它们适合正式方案、教程和演讲页面，样式统一沉淀在 quartz/styles/custom/diagram-components.scss。

推荐边界：

快速逻辑图继续用 Mermaid。
高质量架构图、流程图、能力地图用 HTML diagram component。
复杂交互图再考虑 iframe 或 Quartz component。

Article Templates

Concept Note

## Definition
 
## Why It Matters
 
## Architecture / Flow
 
## Commercial Practice
 
## Common Pitfalls
 
## Interview Answer
 
## Links

Architecture Note

## Context
 
## Problem
 
## Forces
 
## Solution
 
## Reference Architecture
 
## Trade-offs
 
## Governance Checkpoints
 
## AI Enablement

Changelog Note

## Changelog
 
| Date | Change | Files | Notes |
| --- | --- | --- | --- |
| 2026-06-11 | Add style guide | `content/index/Posts/Quartz Style Guide.md` | Demo and usage rules |

Style Changelog

Date	Change	Files	Impact
2026-06-11	新增样式使用指南和 Demo 页面	`content/index/Posts/Quartz Style Guide.md`	为后续文章提供统一样式参考
2026-06-11	新增 Diagram Components 规范	Quartz Diagram Style Guide	为架构图、流程图和能力地图提供 HTML 组件方案
2026-06-11	新增 UI 自动监视入口	UI Evolution Monitor	用 `npm run ui:audit` 检查关键页面和样式组件
2026-06-11	记录已有样式模块清单	`quartz/styles/custom.scss`	明确当前可复用模块
2026-06-03	新增图片布局测试样式	`quartz/styles/images-layouts.scss`	支持宽图、卡片、拼贴和浮动图片
2026-05-26	维护 Quartz Markdown 样式实验页	Quartz MKD	记录 Callout、Gallery Card、Process Steps 等示例

Maintenance Rules

后续新增或修改样式时，同步维护三件事：

在本页 Style Changelog 增加一行记录。
在对应 Demo 小节补一个最小可复制示例。
运行 npm run quartz build，确认 Markdown、SCSS 和 HTML 片段能正常构建。
运行 npm run ui:audit，确认关键页面和样式组件进入构建产物。

Warning

不要在单篇文章里写大量 inline style。优先把可复用布局沉淀到 quartz/styles/custom/*.scss，再在本文补充用法。

Quartz Style Guide

Backlinks

Purpose

Style System Map

Writing Defaults

Text

Links

Tables

Callout Patterns

基础 Callout

Callout Metadata

Column Callout

Caption Callout

Infobox

Style Token

Meta

Gallery Card View

Process Steps

Article Styling Workflow

Choose the article type

Apply the structure

Verify in Quartz

Quote Tabs

Image Layouts

Home Layout

Diagram Components

Article Templates

Concept Note

Architecture Note

Changelog Note

Style Changelog

Maintenance Rules

Links