release: 发布 v0.5.1

新增能力：内置 4 套红头、3 套正式文档和 3 套标书主题，支持主题推荐页边距、页面装饰、页眉页脚和页码；增加结构化公文、项目报告及标书 Front Matter，内置 Fandol 中文字体、两份教程和 14 份主题示例。

桌面工作流：重组更多菜单，增加新建、保存、另存为快捷键和未保存确认；另存为后跟随新路径，主题示例自动切换主题，Desktop 发行包完整携带教程、示例与字体。

问题修复：修正红头标题居中与正式文档字体；围栏代码按正文宽度自动换行，长内容安全断行，至少两行即可在当前页分页，并统一保留 8px 左侧内容留白；Docker Web 镜像正确打包 samples。

兼容与部署：未声明主题推荐设置时继续使用 16mm 默认页边距；Web 隐藏不适用的另存为。正式镜像 yixiong/md-to-pdf:v0.5.1 内容 ID 为 sha256:72f519a69bfd6cb2f6df30c2be938e58ceb6f20e4748a32551874de3d436b276，Compose 健康运行。

验证结果：最终修复前 65 个测试文件、286 项测试通过，最终代码块与主题定向测试 27 项通过；全项目类型检查、生产构建和 git diff --check 通过。容器检出 14 套主题、17 份 Markdown，代码块回归 PDF 为 2 页且无越界。NSIS SHA-256 为 676CCE73D782B0B15AC6BC68F253CFBC4740383583E4DAA98F746EDF9999C5CC，ZIP SHA-256 为 82BF6ADF1200604F145CC86FA3ED193955CF6741EBEE3DF8953483515CFF621F。

packages/core/src/document-profile.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+
+const scalarTextSchema = (maximumLength: number) =>
+  z.preprocess(
+    (value) => {
+      if (
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean"
+      ) {
+        return String(value).trim();
+      }
+      return value;
+    },
+    z.string().min(1).max(maximumLength)
+  );
+
+const shortTextSchema = scalarTextSchema(120);
+const longTextSchema = scalarTextSchema(500);
+const textListSchema = z.preprocess(
+  (value) =>
+    typeof value === "string"
+      ? value
+          .split(/[，,]/u)
+          .map((item) => item.trim())
+          .filter(Boolean)
+      : value,
+  z.array(shortTextSchema).max(30)
+);
+
+export const documentProfileNameSchema = z.enum([
+  "official",
+  "briefing",
+  "project-report",
+  "tender"
+]);
+
+const officialDocumentProfileSchema = z
+  .object({
+    profile: z.literal("official"),
+    issuer: shortTextSchema.optional(),
+    number: shortTextSchema.optional(),
+    secrecy: shortTextSchema.optional(),
+    urgency: shortTextSchema.optional(),
+    signatory: shortTextSchema.optional(),
+    date: shortTextSchema.optional(),
+    copyTo: textListSchema.optional(),
+    printingOffice: shortTextSchema.optional()
+  })
+  .strict();
+
+const briefingDocumentProfileSchema = z
+  .object({
+    profile: z.literal("briefing"),
+    masthead: shortTextSchema.optional(),
+    issue: shortTextSchema.optional(),
+    publisher: shortTextSchema.optional(),
+    signatory: shortTextSchema.optional(),
+    date: shortTextSchema.optional(),
+    contact: longTextSchema.optional()
+  })
+  .strict();
+
+const projectReportDocumentProfileSchema = z
+  .object({
+    profile: z.literal("project-report"),
+    projectName: longTextSchema.optional(),
+    documentType: shortTextSchema.optional(),
+    owner: longTextSchema.optional(),
+    preparedBy: longTextSchema.optional(),
+    version: shortTextSchema.optional(),
+    date: shortTextSchema.optional()
+  })
+  .strict();
+
+const tenderDocumentProfileSchema = z
+  .object({
+    profile: z.literal("tender"),
+    copyMark: shortTextSchema.optional(),
+    projectName: longTextSchema.optional(),
+    projectNumber: shortTextSchema.optional(),
+    volume: shortTextSchema.optional(),
+    bidder: longTextSchema.optional(),
+    representative: shortTextSchema.optional(),
+    date: shortTextSchema.optional()
+  })
+  .strict();
+
+export const documentProfileSchema = z.discriminatedUnion("profile", [
+  officialDocumentProfileSchema,
+  briefingDocumentProfileSchema,
+  projectReportDocumentProfileSchema,
+  tenderDocumentProfileSchema
+]);
+
+export type DocumentProfileName = z.infer<
+  typeof documentProfileNameSchema
+>;
+export type DocumentProfile = z.infer<typeof documentProfileSchema>;

packages/core/src/document.ts

@@ -1,4 +1,5 @@
 import type { ExportConfig } from "./export-config.js";
+import type { DocumentProfile } from "./document-profile.js";
 import type { ThemeFeature } from "./theme.js";
 
 export interface MarkdownDocumentMetadata {
@@ -7,6 +8,7 @@ export interface MarkdownDocumentMetadata {
   subject: string;
   keywords: string[];
   language: string;
+  document?: DocumentProfile;
 }
 
 export interface RenderedMarkdownDocument {

packages/core/src/export-config.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-export const EXPORT_CONFIG_VERSION = 3;
+export const EXPORT_CONFIG_VERSION = 4;
 export const CSS_PIXELS_PER_INCH = 96;
 export const PDF_POINTS_PER_INCH = 72;
 export const MILLIMETERS_PER_INCH = 25.4;
@@ -86,23 +86,39 @@ export function millimetersToPdfPoints(value: number) {
   return (value * PDF_POINTS_PER_INCH) / MILLIMETERS_PER_INCH;
 }
 
-const marginSchema = z.object({
+export const pageMarginsSchema = z.object({
   top: lengthSchema,
   right: lengthSchema,
   bottom: lengthSchema,
   left: lengthSchema
 });
 
-const headerSlotSchema = z.object({
+export const marginModeSchema = z.enum(["theme", "custom"]);
+export const pageDecorationsModeSchema = z.enum(["theme", "custom"]);
+
+export const headerSlotSchema = z.object({
   enabled: z.boolean(),
   content: z.string().max(500)
 });
 
-const headerSchema = z.object({
+const pageDecorationFontFamilySchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(300)
+  .regex(
+    /^[\p{L}\p{N}\s,"'-]+$/u,
+    "页眉页码字体只能包含字体名称、引号和逗号"
+  );
+
+export const headerSchema = z.object({
   enabled: z.boolean(),
   height: lengthSchema,
   showDivider: z.boolean(),
   fontSize: lengthSchema,
+  fontFamily: pageDecorationFontFamilySchema.default(
+    '"Segoe UI", "Microsoft YaHei", sans-serif'
+  ),
   color: z.string(),
   left: headerSlotSchema,
   center: headerSlotSchema,
@@ -114,26 +130,39 @@ export const pageNumberFormatSchema = z.enum([
   "page-total",
   "chinese-page-total",
   "dash-page",
+  "official-page",
   "custom"
 ]);
 
-const footerSchema = z.object({
+export const footerAlignmentSchema = z.enum([
+  "left",
+  "center",
+  "right",
+  "outer"
+]);
+
+export const footerSchema = z.object({
   enabled: z.boolean(),
   height: lengthSchema,
   showDivider: z.boolean(),
   fontSize: lengthSchema,
+  fontFamily: pageDecorationFontFamilySchema.default(
+    '"Segoe UI", "Microsoft YaHei", sans-serif'
+  ),
   color: z.string(),
-  alignment: z.enum(["left", "center", "right"]),
+  alignment: footerAlignmentSchema,
   format: pageNumberFormatSchema,
   template: z.string().max(500).optional(),
-  startFrom: z.number().int().positive()
+  startFrom: z.number().int().positive(),
+  showOnFirstPage: z.boolean().default(true)
 });
 
 const paperSchema = z
   .object({
     format: z.enum(supportedPaperFormats),
     orientation: z.enum(["portrait", "landscape"]),
-    margins: marginSchema
+    marginMode: marginModeSchema,
+    margins: pageMarginsSchema
   })
   .superRefine((paper, context) => {
     const sourceDimensions = paperDimensionsMm[paper.format];
@@ -178,6 +207,7 @@ export const exportConfigSchema = z.object({
   version: z.literal(EXPORT_CONFIG_VERSION),
   name: z.string().min(1).max(100),
   themeId: z.string().min(1),
+  pageDecorationsMode: pageDecorationsModeSchema.default("theme"),
   mermaid: mermaidConfigSchema,
   paper: paperSchema,
   header: headerSchema,
@@ -200,9 +230,30 @@ export type ExportConfig = z.infer<typeof exportConfigSchema>;
 export type MermaidExportConfig = ExportConfig["mermaid"];
 export type PaperFormat = ExportConfig["paper"]["format"];
 export type PaperOrientation = ExportConfig["paper"]["orientation"];
+export type PageMargins = ExportConfig["paper"]["margins"];
+export type MarginMode = ExportConfig["paper"]["marginMode"];
+export type PageDecorationsMode = ExportConfig["pageDecorationsMode"];
 export type HeaderConfig = ExportConfig["header"];
 export type FooterConfig = ExportConfig["footer"];
 
+export const defaultPageMargins: PageMargins = {
+  top: "16mm",
+  right: "16mm",
+  bottom: "16mm",
+  left: "16mm"
+};
+
+export function resolvePageMargins(
+  paper: Pick<ExportConfig["paper"], "marginMode" | "margins">,
+  themeMargins?: PageMargins
+): PageMargins {
+  const source =
+    paper.marginMode === "theme"
+      ? themeMargins ?? defaultPageMargins
+      : paper.margins;
+  return { ...source };
+}
+
 export function getPaperDimensionsMm(
   format: PaperFormat,
   orientation: PaperOrientation
@@ -222,6 +273,7 @@ export const defaultExportConfig: ExportConfig = {
   version: EXPORT_CONFIG_VERSION,
   name: "默认 A4 文档",
   themeId: "typora-github",
+  pageDecorationsMode: "theme",
   mermaid: {
     layout: "dagre",
     theme: "default",
@@ -231,18 +283,15 @@ export const defaultExportConfig: ExportConfig = {
   paper: {
     format: "A4",
     orientation: "portrait",
-    margins: {
-      top: "16mm",
-      right: "16mm",
-      bottom: "16mm",
-      left: "16mm"
-    }
+    marginMode: "theme",
+    margins: { ...defaultPageMargins }
   },
   header: {
     enabled: false,
     height: "8mm",
     showDivider: false,
     fontSize: "3mm",
+    fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif',
     color: "#6b7280",
     left: disabledHeaderSlot,
     center: disabledHeaderSlot,
@@ -253,10 +302,12 @@ export const defaultExportConfig: ExportConfig = {
     height: "8mm",
     showDivider: false,
     fontSize: "3mm",
+    fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif',
     color: "#6b7280",
     alignment: "center",
     format: "page-total",
-    startFrom: 1
+    startFrom: 1,
+    showOnFirstPage: true
   },
   metadata: {
     title: "",

packages/core/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./document.js";
+export * from "./document-profile.js";
 export * from "./document-link.js";
 export * from "./export-config.js";
 export * from "./theme.js";

packages/core/src/theme.ts

@@ -1,4 +1,10 @@
 import { z } from "zod";
+import { documentProfileNameSchema } from "./document-profile.js";
+import {
+  footerSchema,
+  headerSchema,
+  pageMarginsSchema
+} from "./export-config.js";
 
 export const THEME_MANIFEST_VERSION = 1;
 
@@ -12,6 +18,13 @@ export const themeFeatureSchema = z.enum([
   "echarts"
 ]);
 
+export const themeCategorySchema = z.enum([
+  "general",
+  "red-letter",
+  "formal",
+  "tender"
+]);
+
 export const themeManifestSchema = z.object({
   manifestVersion: z.literal(THEME_MANIFEST_VERSION),
   id: z.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
@@ -26,8 +39,20 @@ export const themeManifestSchema = z.object({
   domPreset: z.enum(["typora", "github", "generic"]),
   defaultFontSize: z.string(),
   supportedFeatures: z.array(themeFeatureSchema),
+  category: themeCategorySchema.default("general"),
+  compatibleProfiles: z
+    .array(documentProfileNameSchema)
+    .default([]),
+  pageDefaults: z
+    .object({
+      margins: pageMarginsSchema,
+      header: headerSchema.optional(),
+      footer: footerSchema.optional()
+    })
+    .optional(),
   bundled: z.boolean()
 });
 
 export type ThemeManifest = z.infer<typeof themeManifestSchema>;
 export type ThemeFeature = z.infer<typeof themeFeatureSchema>;
+export type ThemeCategory = z.infer<typeof themeCategorySchema>;

packages/core/tests/export-config.test.ts

@@ -7,6 +7,7 @@ import {
   millimetersToCssPixels,
   millimetersToPdfPoints,
   paperDimensionsMm,
+  resolvePageMargins,
   supportedMermaidLayouts,
   supportedMermaidLooks,
   supportedMermaidThemes,
@@ -33,9 +34,11 @@ describe("导出配置", () => {
 
   it("使用 A4 和 16mm 作为默认纸张配置", () => {
     expect(defaultExportConfig.themeId).toBe("typora-github");
+    expect(defaultExportConfig.pageDecorationsMode).toBe("theme");
     expect(defaultExportConfig.paper).toEqual({
       format: "A4",
       orientation: "portrait",
+      marginMode: "theme",
       margins: {
         top: "16mm",
         right: "16mm",
@@ -46,6 +49,103 @@ describe("导出配置", () => {
     expect(exportConfigSchema.safeParse(defaultExportConfig).success).toBe(true);
   });
 
+  it("提供可由主题推荐的页眉和页码配置", () => {
+    expect(defaultExportConfig.header).toMatchObject({
+      fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif'
+    });
+    expect(defaultExportConfig.footer).toMatchObject({
+      fontFamily: '"Segoe UI", "Microsoft YaHei", sans-serif',
+      alignment: "center",
+      format: "page-total",
+      showOnFirstPage: true
+    });
+
+    const parsedLegacyV4 = exportConfigSchema.parse({
+      ...defaultExportConfig,
+      pageDecorationsMode: undefined,
+      header: {
+        ...defaultExportConfig.header,
+        fontFamily: undefined
+      },
+      footer: {
+        ...defaultExportConfig.footer,
+        fontFamily: undefined,
+        showOnFirstPage: undefined
+      }
+    });
+
+    expect(parsedLegacyV4.pageDecorationsMode).toBe("theme");
+    expect(parsedLegacyV4.header.fontFamily).toContain("Microsoft YaHei");
+    expect(parsedLegacyV4.footer.fontFamily).toContain("Microsoft YaHei");
+    expect(parsedLegacyV4.footer.showOnFirstPage).toBe(true);
+  });
+
+  it("支持公文页码格式和奇偶页外侧对齐", () => {
+    expect(
+      exportConfigSchema.safeParse({
+        ...defaultExportConfig,
+        footer: {
+          ...defaultExportConfig.footer,
+          fontFamily: '"Mdpdf Fandol Song", SimSun, serif',
+          fontSize: "4.94mm",
+          color: "#000000",
+          alignment: "outer",
+          format: "official-page",
+          showOnFirstPage: false
+        }
+      }).success
+    ).toBe(true);
+  });
+
+  it("拒绝可能逃逸 CSS 字体声明的页眉页码字体", () => {
+    expect(
+      exportConfigSchema.safeParse({
+        ...defaultExportConfig,
+        footer: {
+          ...defaultExportConfig.footer,
+          fontFamily: 'serif; color: red'
+        }
+      }).success
+    ).toBe(false);
+  });
+
+  it("按主题、自定义和全局默认顺序解析页边距", () => {
+    const themeMargins = {
+      top: "37mm",
+      right: "26mm",
+      bottom: "35mm",
+      left: "28mm"
+    };
+    expect(resolvePageMargins(defaultExportConfig.paper, themeMargins)).toEqual(
+      themeMargins
+    );
+    expect(resolvePageMargins(defaultExportConfig.paper)).toEqual({
+      top: "16mm",
+      right: "16mm",
+      bottom: "16mm",
+      left: "16mm"
+    });
+    expect(
+      resolvePageMargins(
+        {
+          marginMode: "custom",
+          margins: {
+            top: "10mm",
+            right: "11mm",
+            bottom: "12mm",
+            left: "13mm"
+          }
+        },
+        themeMargins
+      )
+    ).toEqual({
+      top: "10mm",
+      right: "11mm",
+      bottom: "12mm",
+      left: "13mm"
+    });
+  });
+
   it("提供 Mermaid 官方布局、主题、外观和字体默认值", () => {
     expect(supportedMermaidLayouts).toEqual(["dagre", "elk"]);
     expect(supportedMermaidLooks).toEqual([

packages/core/tests/theme.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from "vitest";
+import { themeManifestSchema } from "../src/theme.js";
+
+describe("主题清单", () => {
+  it("允许主题推荐页边距、页眉和页码配置", () => {
+    const parsed = themeManifestSchema.parse({
+      manifestVersion: 1,
+      id: "official-test",
+      name: "公文测试主题",
+      version: "0.5.1",
+      description: "测试主题推荐页面配置。",
+      author: "md-to-pdf contributors",
+      license: "项目自有",
+      entry: "theme.css",
+      domPreset: "generic",
+      defaultFontSize: "21.333px",
+      supportedFeatures: ["table"],
+      category: "red-letter",
+      compatibleProfiles: ["official"],
+      pageDefaults: {
+        margins: {
+          top: "37mm",
+          right: "26mm",
+          bottom: "35mm",
+          left: "28mm"
+        },
+        header: {
+          enabled: false,
+          height: "8mm",
+          showDivider: false,
+          fontSize: "4.94mm",
+          fontFamily: '"Mdpdf Fandol Song", SimSun, serif',
+          color: "#000000",
+          left: { enabled: false, content: "" },
+          center: { enabled: false, content: "" },
+          right: { enabled: false, content: "" }
+        },
+        footer: {
+          enabled: true,
+          height: "7mm",
+          showDivider: false,
+          fontSize: "4.94mm",
+          fontFamily: '"Mdpdf Fandol Song", SimSun, serif',
+          color: "#000000",
+          alignment: "outer",
+          format: "official-page",
+          startFrom: 1,
+          showOnFirstPage: false
+        }
+      },
+      bundled: true
+    });
+
+    expect(parsed.pageDefaults?.footer).toMatchObject({
+      alignment: "outer",
+      format: "official-page",
+      showOnFirstPage: false
+    });
+  });
+});