技述｜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/。分享網址必須回傳文件位元組並允許 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"
            }
          ]
        }
      ]
    ]
  }
]