技述｜JS.GRIPE

主题开发规范

EdgePress 开发指南

让内容可以迁移，让主题专注呈现。

主题负责共享布局和页面元素样式。页面文案与媒体归属于站点内容，这样切换主题时不必重写页面。

分开页面内容与视觉呈现

页面文件定义行、元素、不同语言的文案、链接和媒体引用。主题负责共享 HTML 布局、字体、颜色、间距、响应式行为，以及页面元素的视觉样式。

保持主题名称稳定，并确保各个主题都能呈现相同的页面元素。切换主题后，访客仍能读到相同的信息。

项目目录结构
config.yml
content/
  pages/home/en.md
  assets/images/home-banner.webp
themes/
  lumen/
    theme.json
    layouts/layout.html
    layouts/partials/
    assets/style.css

将媒体文件放在内容目录

将页面插画、横幅、标志和下载文件放在 content/assets/。EdgePress 会按相同路径发布到站点根目录。例如，content/assets/images/home-banner.webp 对应 /images/home-banner.webp。

themes/<name>/assets/ 保留给共享样式表和主题交互。这样页面图片不会绑定某个主题，切换主题后也能继续使用。

为图片写清楚替代文本并声明原始尺寸。如果页面需要多种图片尺寸，再提供响应式候选项。

构建无障碍的共享布局

使用语义化的 header、navigation、main 和 footer 区域。保留跳转链接、唯一 main 区域、清晰的键盘焦点样式和一个页面级 h1。

普通模板占位符必须转义。原样输出仅用于生成的页面内容、JSON-LD 和导航标记。页面文字、媒体说明和网址要经过页面渲染器校验。

同时检查浅色与深色配色下的文字和控件。遵循减少动态效果的系统偏好，并确保窄屏上的控件易于操作。

为每个主题设定清晰方向

颜色、字体、边框、表面和元素间距都放在主题样式表中。使用共享 CSS 变量管理配色，不要把视觉选择写进页面 JSON。

JS.GRIPE 的主题展示了不同方向。Atelier 使用水墨色彩和旧纸质感，Default 采用简约线稿，Signal 使用暖色田园绘本配色，Lumen 保持银蓝色的编辑风格。

切换与检查主题

  1. 选择主题

    在根目录 config.yml 设置主题名称，例如选择 lumen。

  2. 完善共享样式

    编辑主题布局、局部模板、样式表和必要的本地交互脚本。每种页面元素都应易读，并符合主题的视觉方向。

  3. 检查不同尺寸的页面

    构建网站并运行 EdgePress 页面检查。发布前检查键盘焦点、颜色对比、媒体说明、手机布局和不同配色方案。

    edgepress check

显示单个项目的文章

使用 post-list 的 category: edgepress 或 categories: [博客, 未分类] 筛选栏目，按日期由新到旧排列，优先选择当前语言版本。count 可设为 1 到 12；单个分类超出的文章链接到当前语言分类归档。

项目文章列表
[
  {
    "columns": 1,
    "cells": [
      [
        {
          "type": "post-list",
          "title": "EdgePress articles",
          "category": "edgepress",
          "count": 6
        }
      ]
    ]
  }
]

在文章前置数据加入 category: edgepress；省略分类时默认未分类。标签仅在文章页展示，移除 tag 筛选和标签归档。site.archive.categories 控制主见闻栏目；首页分页时使用相同分类。

内置主题随站点打包 Noto Sans、Noto Serif 和简繁中文可变字体，不请求字体 CDN。WOFF2 按 Unicode 字符范围分片，只加载当前页面使用的字形；繁体语言优先使用繁体字形。界面、文章、Pages 和代码中的中文均可使用本地字形，不要求访客安装中文字体。

自定义主题使用统一字体变量
:root { font-family: var(--edgepress-font-sans); }
h1, h2 { font-family: var(--edgepress-font-serif); }
pre, code { font-family: var(--edgepress-font-mono); }

字体覆盖拉丁字母、希腊字母、西里尔字母及常用简繁中文，并非完整 Unicode。增加阿拉伯语等其他文字系统的语言包时，应同时加入对应 Noto 字体与 unicode-range；保持同源加载、OFL 许可证和内容哈希。fonts:sync 仅维护字体资源，普通构建无需下载字体。

PDF、DOC/DOCX、PPT/PPTX 和 XLS/XLSX 使用随站点打包的浏览器渲染器，自动读取并预览本地文档，不需要 Office 软件或转换服务器。本地文档放在 content/assets/documents/。共享 URL 必须返回文档字节并允许 CORS，注册为 external-api 同意服务，取得当前有效同意后才发出请求。

文章或 Pages 文本
!document[年度报告](/documents/report.docx)
!document[共享 PDF](https://files.example/download/123){format=pdf service=documents}
Pages 文档块
[
  {
    "type": "document",
    "title": "年度报告",
    "src": "/documents/report.xlsx"
  }
]

文档以带页码的连续分页展示，不再使用上下页按钮。document 插入 PDF 和 Office；media-viewer 插入图片、视频或混合附件。只加载选中的媒体，点击播放后才加载视频。远程资源仍须登记服务、配置 CSP 并等待授权。

Pages 查看器元素
[
  {
    "columns": 1,
    "cells": [
      [
        {
          "type": "document",
          "title": "Report",
          "src": "/documents/report.pdf"
        },
        {
          "type": "media-viewer",
          "title": "Photos and video",
          "items": [
            {
              "type": "image",
              "src": "/images/photo.webp",
              "originalSrc": "/images/photo-original.webp",
              "alt": "Detail of the project interface"
            },
            {
              "type": "video",
              "src": "/videos/walkthrough.mp4",
              "poster": "/images/poster.webp",
              "label": "Project walkthrough",
              "captions": "/videos/walkthrough.en.vtt",
              "captionLanguage": "en"
            }
          ]
        }
      ]
    ]
  }
]