feat: 扩展本地主题兼容能力
This commit is contained in:
SkyJourney
+275
@@ -0,0 +1,275 @@
|
||||
# 主题开发指南
|
||||
|
||||
主题用于控制 Markdown 正文的字体、颜色、标题、表格、引用、代码块、公式和图表等视觉样式。纸张尺寸、页边距、页眉页脚、页码和 PDF 元数据属于导出配置，不应写入主题。
|
||||
|
||||
网页预览与未来的 Chromium PDF 必须使用相同的 `<article id="write">`、Markdown 渲染结果、主题 CSS 和打印 CSS。
|
||||
|
||||
## 1. 主题位置
|
||||
|
||||
项目支持两类主题：
|
||||
|
||||
```text
|
||||
themes/<theme-id>/ 随项目分发的内置主题
|
||||
.local/themes/<theme-id>/ 仅供当前设备使用的本地主题
|
||||
```
|
||||
|
||||
- 内置主题的 `bundled` 必须为 `true`，并具有允许项目分发的明确许可证。
|
||||
- 本地主题的 `bundled` 必须为 `false`，整个 `.local/` 目录已被 Git 忽略。
|
||||
- 主题目录名必须与清单中的 `id` 完全一致。
|
||||
|
||||
## 2. 目录结构
|
||||
|
||||
最小主题：
|
||||
|
||||
```text
|
||||
.local/themes/example/
|
||||
├── theme.json
|
||||
└── theme.css
|
||||
```
|
||||
|
||||
包含基础层、打印层和资源的主题：
|
||||
|
||||
```text
|
||||
.local/themes/example/
|
||||
├── theme.json
|
||||
├── base.css
|
||||
├── theme.css
|
||||
├── print.css
|
||||
├── partials/
|
||||
│ └── code.css
|
||||
├── fonts/
|
||||
│ └── example.woff2
|
||||
└── images/
|
||||
└── quote.svg
|
||||
```
|
||||
|
||||
每个主题必须自包含，不得通过 `../` 引用主题目录外的共享文件。
|
||||
|
||||
## 3. `theme.json`
|
||||
|
||||
完整示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"manifestVersion": 1,
|
||||
"id": "example",
|
||||
"name": "示例主题",
|
||||
"version": "1.0.0",
|
||||
"description": "用于演示主题清单的本地主题。",
|
||||
"author": "示例作者",
|
||||
"license": "MIT",
|
||||
"base": "base.css",
|
||||
"entry": "theme.css",
|
||||
"print": "print.css",
|
||||
"domPreset": "typora",
|
||||
"defaultFontSize": "16px",
|
||||
"supportedFeatures": [
|
||||
"code",
|
||||
"table",
|
||||
"task-list",
|
||||
"footnote",
|
||||
"katex",
|
||||
"mermaid"
|
||||
],
|
||||
"bundled": false
|
||||
}
|
||||
```
|
||||
|
||||
字段说明：
|
||||
|
||||
| 字段 | 必填 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `manifestVersion` | 是 | 当前固定为 `1`。 |
|
||||
| `id` | 是 | 小写字母、数字和连字符组成，且必须与目录名一致。 |
|
||||
| `name` | 是 | 主题选择器中显示的名称。 |
|
||||
| `version` | 是 | 主题版本，最长 30 个字符。 |
|
||||
| `description` | 是 | 主题用途与来源说明。 |
|
||||
| `author` | 是 | 作者或维护者。 |
|
||||
| `license` | 是 | 许可证或本地使用边界。 |
|
||||
| `base` | 否 | 可复用的基础 CSS。 |
|
||||
| `entry` | 是 | 主题主体 CSS。 |
|
||||
| `print` | 否 | 打印 CSS，建议将规则放入 `@media print`。 |
|
||||
| `domPreset` | 是 | 当前支持 `typora`、`github`、`generic`。 |
|
||||
| `defaultFontSize` | 是 | 主题建议的正文基准字号。 |
|
||||
| `supportedFeatures` | 是 | 支持能力声明。 |
|
||||
| `bundled` | 是 | 内置主题为 `true`，本地主题为 `false`。 |
|
||||
|
||||
支持能力值包括：
|
||||
|
||||
```text
|
||||
code
|
||||
table
|
||||
task-list
|
||||
footnote
|
||||
katex
|
||||
mermaid
|
||||
```
|
||||
|
||||
## 4. CSS 组合顺序
|
||||
|
||||
服务端按以下顺序组合 CSS：
|
||||
|
||||
```text
|
||||
base
|
||||
→ entry
|
||||
→ print
|
||||
```
|
||||
|
||||
后加载的规则可以覆盖前面的规则。推荐职责：
|
||||
|
||||
- `base`：元素归一化、通用排版和分页基础规则。
|
||||
- `entry`：颜色、字体、标题、表格、引用和代码块等主题视觉。
|
||||
- `print`：只在打印时生效的分页与颜色调整。
|
||||
|
||||
如果主题不需要基础层或打印层，可以省略相应字段。
|
||||
|
||||
## 5. DOM 约定
|
||||
|
||||
渲染器输出的正文根节点固定为：
|
||||
|
||||
```html
|
||||
<article id="write">
|
||||
<!-- 安全 Markdown HTML -->
|
||||
</article>
|
||||
```
|
||||
|
||||
主题应优先使用以下选择器：
|
||||
|
||||
```css
|
||||
#write {
|
||||
color: #24292f;
|
||||
font-family: system-ui, sans-serif;
|
||||
line-height: 1.7;
|
||||
}
|
||||
|
||||
#write h1,
|
||||
#write h2 {
|
||||
break-after: avoid-page;
|
||||
}
|
||||
|
||||
#write table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
border-spacing: 0;
|
||||
}
|
||||
|
||||
#write th,
|
||||
#write td {
|
||||
border: 1px solid #d0d7de;
|
||||
padding: 0.5em 0.75em;
|
||||
}
|
||||
```
|
||||
|
||||
不要依赖 Typora 编辑器窗口、侧边栏、焦点状态或源码模式专用 DOM。当前预览和未来 PDF 不会添加 `typora-export` 类，纸张边距由导出配置负责。
|
||||
|
||||
## 6. 字体、图片和 CSS 导入
|
||||
|
||||
CSS 中可以使用主题目录内的相对资源：
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: "Example";
|
||||
src: url("./fonts/example.woff2") format("woff2");
|
||||
}
|
||||
|
||||
#write blockquote {
|
||||
background-image: url("./images/quote.svg");
|
||||
}
|
||||
```
|
||||
|
||||
嵌套 CSS 可以使用相对于自身文件的资源：
|
||||
|
||||
```css
|
||||
/* theme.css */
|
||||
@import "partials/code.css";
|
||||
```
|
||||
|
||||
```css
|
||||
/* partials/code.css */
|
||||
@font-face {
|
||||
font-family: "Example Mono";
|
||||
src: url("./fonts/example-mono.woff2") format("woff2");
|
||||
}
|
||||
```
|
||||
|
||||
允许通过资源接口提供的扩展名：
|
||||
|
||||
```text
|
||||
.gif .jpeg .jpg .png .svg .webp
|
||||
.ttf .woff .woff2
|
||||
```
|
||||
|
||||
CSS `@import` 会在服务端展开，不作为静态资源直接返回。
|
||||
|
||||
## 7. 安全限制
|
||||
|
||||
主题注册器会拒绝：
|
||||
|
||||
- HTTP、HTTPS、协议相对地址和其他外部 URL；
|
||||
- 绝对文件路径；
|
||||
- 含 `..` 的 CSS、字体或图片路径；
|
||||
- 逃出主题目录的符号链接；
|
||||
- 非文件资源；
|
||||
- CSS 循环导入；
|
||||
- 超过 8 层的 CSS 导入；
|
||||
- 不支持的 `@import` 语法；
|
||||
- 不在允许列表中的静态资源类型。
|
||||
|
||||
`data:` URL 和同文档 `#fragment` 引用可以保留。Typora 专用的 `@include-when-export` 外部字体声明会被移除，主题应同时提供本地字体文件或可靠的系统字体回退。
|
||||
|
||||
## 8. 创建本地主题
|
||||
|
||||
1. 在 `.local/themes` 下创建与主题 ID 同名的目录。
|
||||
2. 编写 `theme.json` 和入口 CSS。
|
||||
3. 启动开发服务：
|
||||
|
||||
```powershell
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. 打开主题选择器检查主题是否出现。
|
||||
5. 使用包含标题、表格、代码、公式和 Mermaid 的 Markdown 验证。
|
||||
6. 检查浏览器控制台、窄屏布局和打印样式。
|
||||
|
||||
主题清单或资源路径无效时，服务端会拒绝加载该主题，而不是跳过安全检查。
|
||||
|
||||
## 9. 本地导入 Typora 默认主题
|
||||
|
||||
本机安装 Typora 后，可以导入 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题：
|
||||
|
||||
```powershell
|
||||
npm run theme:import-typora
|
||||
```
|
||||
|
||||
导入工具从 Typora 安装目录读取：
|
||||
|
||||
```text
|
||||
resources/style/base.css
|
||||
resources/style/themes/
|
||||
```
|
||||
|
||||
每套主题都会获得独立的 `typora-base.css`、主题 CSS、资源目录和 `theme.json`。已有目标默认不会被覆盖。
|
||||
|
||||
确认替换现有本地副本时使用：
|
||||
|
||||
```powershell
|
||||
npm run theme:import-typora -- --replace
|
||||
```
|
||||
|
||||
替换前会先在临时目录完整生成主题；旧副本移动到：
|
||||
|
||||
```text
|
||||
.local/theme-backups/
|
||||
```
|
||||
|
||||
Typora 当前没有为这些文件提供允许项目再分发的明确许可证，因此导入结果只能保存在 `.local`，不得提交到 Git、打包进容器或随项目发布。
|
||||
|
||||
## 10. 提交内置主题前检查
|
||||
|
||||
- 许可证明确允许再分发，并在清单和说明中记录。
|
||||
- 主题目录不包含用户文档、临时文件或无关资源。
|
||||
- `npm test` 通过。
|
||||
- `npm run typecheck` 通过。
|
||||
- `npm run build` 通过。
|
||||
- `git diff --check` 通过。
|
||||
- 浏览器检查表格、长代码块、KaTeX、Mermaid、字体和分页边界。
|
||||
Reference in New Issue
Block a user