edgepress 2026.10.1 → 2026.10.13

package/content/pages/page-authoring/zh-cn.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "../../../schemas/pages.schema.json",
+  "title": "用括号看懂 Pages 的包含关系",
+  "lang": "zh-CN",
+  "slug": "page-authoring",
+  "description": "使用 JSON 页面、本地结构说明和可折叠对象，读懂行、单元格与元素。",
+  "blocks": [
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "hero",
+            "title": "用括号看懂 Pages 的包含关系",
+            "text": "使用 JSON 页面、本地结构说明和可折叠对象，读懂行、单元格与元素。"
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "code",
+            "title": "完整的双栏 JSON 页面",
+            "language": "json",
+            "code": "{\n  \"title\": \"My page\",\n  \"lang\": \"en\",\n  \"slug\": \"my-page\",\n  \"blocks\": [\n    {\n      \"columns\": 2,\n      \"cells\": [\n        [\n          {\n            \"type\": \"heading\",\n            \"level\": 2,\n            \"text\": \"About this project\"\n          },\n          {\n            \"type\": \"text\",\n            \"text\": \"A small tool for everyday writing.\"\n          }\n        ],\n        [\n          {\n            \"type\": \"link-list\",\n            \"title\": \"Read more\",\n            \"items\": [\n              {\n                \"label\": \"Project\",\n                \"url\": \"/[launge]/project-introduction/\"\n              }\n            ]\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "paragraphs": [
+              "保存为 content/pages/my-page/en.json。语言文件名须小写，lang 匹配已启用的语言；中文页面可用 zh-cn.json。homepage: true 发布为对应语言首页，slug 定义普通页面路径。JSON 页面不使用 YAML 前置数据，也没有 Markdown 正文。",
+              "blocks 数组按顺序放页面行。一行的 columns 从 1 到 4，cells 内须有相同个数的单元格数组。每个单元格至少包含一个元素，元素从上到下显示。",
+              "JSON 键名和字符串使用双引号。花括号放对象，方括号放数组，同级项目用逗号分开。不要新增 elements 字段；最内层数组直接放元素。",
+              "section 的 blocks 放子元素，不是新的页面行。文字用 text 或 paragraphs，代码用 code 字符串，内部换行使用 \\n。文章仍放在 content/posts，用 Markdown 编写。",
+              "本地 $schema 让 VS Code 提供字段说明和结构校验。对象与数组可以逐级折叠，大纲能展示它们的上下关系。旧 .md 页面仍可构建，但同一语言不要同时保留两种页面格式。"
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "data-table",
+            "title": "常用元素（字段）",
+            "headers": [
+              "用途",
+              "元素与关键字段"
+            ],
+            "rows": [
+              [
+                "Title",
+                "heading (level, text)"
+              ],
+              [
+                "Prose",
+                "text (text OR paragraphs)"
+              ],
+              [
+                "Group",
+                "section (title, blocks)"
+              ],
+              [
+                "Code",
+                "code (language, code)"
+              ],
+              [
+                "Articles",
+                "post-list (title, category OR categories, count)"
+              ],
+              [
+                "Document",
+                "document (title, src)"
+              ],
+              [
+                "Gallery",
+                "media-viewer (title, items)"
+              ]
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "text": "运行 npm run pages:format 预览迁移，再用 npm run pages:format -- --write 写入。工具在移除旧文件前校验字段值与顺序；随后运行 npm run build 检查实际呈现。"
+          }
+        ]
+      ]
+    }
+  ]
+}

package/content/pages/plugin-development/en.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "../../../schemas/pages.schema.json",
+  "title": "Plugin development",
+  "lang": "en",
+  "slug": "plugin-development",
+  "description": "Extend static websites with trusted build plugins and consent-registered external services.",
+  "blocks": [
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "hero",
+            "eyebrow": "Extension guide",
+            "title": "Connect trusted build code, browser providers, and backend services.",
+            "text": "Build-time plugins run in Node. Browser services load only after visitor consent. Backends are independently deployed."
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 2,
+      "cells": [
+        [
+          {
+            "type": "section",
+            "title": "Build-time plugins",
+            "tone": "soft",
+            "blocks": [
+              {
+                "type": "text",
+                "paragraphs": [
+                  "Local JavaScript modules in plugins/ may transform source documents, register hooks or renderers, and generate routes. They execute with the build process permissions, so only load code reviewed by the project owner.",
+                  "The starter consent plugin adds a privacy panel after the shared page layout. Build plugins are trusted code and are not deployed as browser scripts."
+                ]
+              },
+              {
+                "type": "code",
+                "title": "Register a route generator",
+                "language": "js",
+                "code": "export default function projectMeta(api) {\n  api.registerGenerator('project-meta', ({ site }) => ({\n    path: 'project-meta.json',\n    body: JSON.stringify({\n      title: site.config.site.title,\n      posts: site.posts.length\n    }),\n    contentType: 'application/json; charset=utf-8'\n  }));\n}\n"
+              }
+            ]
+          }
+        ],
+        [
+          {
+            "type": "section",
+            "title": "Tracking, statistics, advertising, and CAPTCHA",
+            "tone": "soft",
+            "blocks": [
+              {
+                "type": "text",
+                "paragraphs": [
+                  "Add browser providers in config.yml under plugins.consent.services. Each service needs a unique ID, provider, purpose, dataCategories, recipient, retention, a privacyUrl pointing to the provider's current privacy information, and its public site identifier. privacyUrl must be an HTTPS URL. Localized fields are maps keyed by every enabled locale, such as en and zh-CN.",
+                  "Available providers include Google Tag Manager and Meta Pixel; Cloudflare Web Analytics, Google Analytics, and Baidu Tongji; Google AdSense; and Cloudflare Turnstile, Google reCAPTCHA, and hCaptcha.",
+                  "Set plugins.consent.proposedDate to the YYYY-MM-DD date the notice was drafted. Set effectiveDate when the notice takes effect; omit it while no effective date has been set. Updating either date makes saved consent stale, so visitors are asked again.",
+                  "Provider code is imported only after the visitor accepts that integration. The first layer offers accept and reject together; service data and individual switches are available in its details. Keep CAPTCHA secret keys out of config.yml and client code. The server must submit each CAPTCHA response to the provider verification API before accepting a form."
+                ]
+              },
+              {
+                "type": "notice",
+                "title": "Operator details",
+                "text": "Fill privacy.controller.name, privacy.controller.contact, and privacy.policyUrl before configuring any browser provider. The build rejects provider services when the controller name or contact is blank.",
+                "tone": "warning"
+              }
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "Optional external services",
+            "paragraphs": [
+              "Register external-api or external-widget under plugins.consent.services in config.yml. Services require their own HTTPS origin, complete privacy disclosures and explicit visitor consent.",
+              "The site is static. API authentication, authorization, CAPTCHA verification, input validation and rate limits belong to the independently deployed backend. Operator Secrets never enter browser configuration."
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "section",
+            "title": "Content security and maintenance",
+            "blocks": [
+              {
+                "type": "text",
+                "paragraphs": [
+                  "The built-in Markdown renderer sanitizes post output. Custom renderers, plugins, themes, and files in static/ are trusted project code; review changes before building or deploying. Do not put secrets in posts, themes, or public assets.",
+                  "edgepress iterate writes a report-only review plan under .edgepress/reports/. It does not edit source files, update dependencies, or deploy. edgepress security checks dependency advisories. Review the lockfile and generated page report before deployment, and keep a known-good deployment for rollback."
+                ]
+              },
+              {
+                "type": "code",
+                "title": "Review project changes",
+                "language": "sh",
+                "code": "edgepress security\nedgepress iterate\nedgepress check\nedgepress server\n"
+              }
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "iask",
+            "text": "iask owns comments, styles, identity and stickers. Register an external-widget with backendUrl and moduleUrl under plugins.consent.services; the host only loads it after opt-in."
+          },
+          {
+            "type": "link-list",
+            "title": "Install and integrate",
+            "items": [
+              {
+                "label": "Installation and EdgePress integration",
+                "url": "https://github.com/jsw-teams/iask/blob/main/docs/edgepress.md"
+              },
+              {
+                "label": "iask release notes",
+                "url": "https://github.com/jsw-teams/iask/blob/main/CHANGELOG.md"
+              }
+            ]
+          },
+          {
+            "type": "code",
+            "title": "Optional page discussion block",
+            "language": "json",
+            "code": "{\n  \"blocks\": [\n    {\n      \"columns\": 1,\n      \"cells\": [\n        [\n          {\n            \"type\": \"service\",\n            \"integration\": \"github-comments\"\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "Shared images and videos",
+            "text": "Register ishare as an oembed service in plugins.consent.services, with its HTTPS backendUrl and complete privacy disclosures. The page keeps a local placeholder until the visitor consents and clicks Load media. Metadata uses fixed /api and request headers; the attributed iframe remains on the configured service origin."
+          },
+          {
+            "type": "code",
+            "title": "Pages embed syntax",
+            "language": "json",
+            "code": "{\n  \"blocks\": [\n    {\n      \"columns\": 1,\n      \"cells\": [\n        [\n          {\n            \"type\": \"text\",\n            \"text\": \"!embed[ishare](https://share.js.gripe/s/REPLACE_WITH_REAL_SHARE_ID)\"\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          },
+          {
+            "type": "link-list",
+            "title": "Service documentation",
+            "items": [
+              {
+                "label": "ishare",
+                "url": "https://github.com/jsw-teams/ishare/blob/main/docs/zh-cn.md"
+              }
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "General social media embeds",
+            "text": "Only YouTube and X are registered as general media presets; share.js.gripe enables none. Register custom services in config.yml as needed. Set enabled: false to remove its consent entry and network permissions; its block retains a local disabled notice and the original link. oembedEndpoint metadata is cached at build time; the browser still waits for consent and a load click. sourceOrigins validates shared links; embedOrigins permits media hosts; embedScripts contains exact optional vendor script URLs. Instagram and Facebook use official public-content iframes. Private or embed-restricted posts may be unavailable. Replace the Mastodon instance with your actual instance."
+          },
+          {
+            "type": "code",
+            "title": "Pages embed syntax",
+            "language": "json",
+            "code": "{\n  \"blocks\": [\n    {\n      \"columns\": 2,\n      \"cells\": [\n        [\n          {\n            \"type\": \"text\",\n            \"heading\": \"Watch with context\",\n            \"text\": \"Describe the media next to its player.\"\n          }\n        ],\n        [\n          {\n            \"type\": \"text\",\n            \"text\": \"!embed[youtube](https://www.youtube.com/watch?v=jNQXAC9IVRw)\"\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          },
+          {
+            "type": "text",
+            "heading": "Custom oEmbed and navigation",
+            "text": "Add a flat provider: oembed service in config.yml with disclosures, backendUrl, oembedEndpoint and permitted source/media origins. Public endpoints must not contain secrets; authenticated providers need an external gateway. Pages text blocks use the same !embed[service](URL) syntax as article bodies. Navigation and footer links support target: _self or target: _blank, including dropdown choices."
+          },
+          {
+            "type": "text",
+            "heading": "Automatic CSP from service configuration",
+            "text": "The build generates a Content-Security-Policy response header and a matching HTML meta policy for static hosting. Enabled consent services contribute only their permitted script, connection, frame and media origins. Disabled services contribute no permissions. CSP does not grant consent: visitors must still allow the service before a resource loads. Custom services can add an optional csp map, for example connect-src: [https://api.example.com]; only HTTPS origins are accepted. Keep first-party upload permissions in the source _headers file. GTM containers that add other providers need those domains explicitly configured."
+          }
+        ]
+      ]
+    }
+  ]
+}

package/content/pages/plugin-development/zh-cn.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "../../../schemas/pages.schema.json",
+  "title": "插件开发",
+  "lang": "zh-CN",
+  "slug": "plugin-development",
+  "description": "使用可信构建插件和经过 consent 注册的外部服务扩展静态网站。",
+  "blocks": [
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "hero",
+            "eyebrow": "扩展指南",
+            "title": "连接可信构建代码、浏览器供应商和后端服务。",
+            "text": "构建插件在 Node 中运行，浏览器服务只在访客选择后加载，后端独立部署。"
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 2,
+      "cells": [
+        [
+          {
+            "type": "section",
+            "title": "构建插件",
+            "tone": "soft",
+            "blocks": [
+              {
+                "type": "text",
+                "paragraphs": [
+                  "plugins/ 中的本地 JavaScript 模块可以转换源文档、注册钩子或渲染器，并生成路由。它们拥有构建进程的权限，因此只应加载项目负责人审查过的代码。",
+                  "起始同意插件会在共享页面布局后添加隐私面板。构建插件属于可信代码，不会作为浏览器脚本发布。"
+                ]
+              },
+              {
+                "type": "code",
+                "title": "注册路由生成器",
+                "language": "js",
+                "code": "export default function projectMeta(api) {\n  api.registerGenerator('project-meta', ({ site }) => ({\n    path: 'project-meta.json',\n    body: JSON.stringify({\n      title: site.config.site.title,\n      posts: site.posts.length\n    }),\n    contentType: 'application/json; charset=utf-8'\n  }));\n}\n"
+              }
+            ]
+          }
+        ],
+        [
+          {
+            "type": "section",
+            "title": "跟踪、统计、广告和人机验证",
+            "tone": "soft",
+            "blocks": [
+              {
+                "type": "text",
+                "paragraphs": [
+                  "在 config.yml 的 plugins.consent.services 下添加浏览器供应商。每项需要唯一 ID、provider、purpose、dataCategories、recipient、retention、指向供应商当前隐私说明的 privacyUrl，以及公开站点标识。privacyUrl 必须是 HTTPS 地址。多语言字段需使用语言映射，覆盖已启用的每种语言，例如 en 与 zh-CN。",
+                  "可用供应商包括 Google Tag Manager 和 Meta Pixel；Cloudflare Web Analytics、Google Analytics 和百度统计；Google AdSense；以及 Cloudflare Turnstile、Google reCAPTCHA 和 hCaptcha。",
+                  "plugins.consent.proposedDate 必须设置为 YYYY-MM-DD 格式的告知拟定日期。告知生效后再设置 effectiveDate；尚未生效时可以省略。修改任一日期都会使旧的同意记录失效，并重新询问访客。",
+                  "只有访客接受对应集成后才会导入供应商代码。首层同时提供接受和拒绝，数据详情与逐项开关位于展开内容中。不要把 CAPTCHA 密钥放入 config.yml 或客户端代码。服务器必须在接受表单前将每个 CAPTCHA 响应提交给供应商验证 API。"
+                ]
+              },
+              {
+                "type": "notice",
+                "title": "运营者信息",
+                "text": "配置浏览器供应商前，请填写 privacy.controller.name、privacy.controller.contact 和 privacy.policyUrl。控制者名称或联系方式为空时，构建器会拒绝启用供应商服务。",
+                "tone": "warning"
+              }
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "可选外部服务",
+            "paragraphs": [
+              "在 config.yml 的 plugins.consent.services 注册 external-api 或 external-widget。服务使用独立 HTTPS 地址、完整隐私说明和访客明确选择。",
+              "网站只提供静态前端。API 身份验证、授权、验证码校验、输入验证和速率限制由独立后端负责，运营者 Secret 不进入浏览器配置。"
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "section",
+            "title": "内容安全与维护",
+            "blocks": [
+              {
+                "type": "text",
+                "paragraphs": [
+                  "内置 Markdown 渲染器会清理文章输出。自定义渲染器、插件、主题和 static/ 中的文件都属于可信项目代码；构建或部署前应审查变更。不要将密钥放在文章、主题或公开资源中。",
+                  "edgepress iterate 会在 .edgepress/reports/ 下生成只读维护计划，不会修改源文件、更新依赖或部署。edgepress security 检查依赖安全公告。部署前请审查锁文件和页面报告，并保留可用于回滚的已知稳定部署。"
+                ]
+              },
+              {
+                "type": "code",
+                "title": "审查项目变更",
+                "language": "sh",
+                "code": "edgepress security\nedgepress iterate\nedgepress check\nedgepress server\n"
+              }
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "我提问",
+            "text": "显示经过验证的 GitHub 身份和头像，可从本地图片、GIF 图集中选择表情包，支持删除自己的评论。读者选中评论后才加载讨论。"
+          },
+          {
+            "type": "link-list",
+            "title": "安装与接入",
+            "items": [
+              {
+                "label": "安装及 EdgePress 接入说明",
+                "url": "https://github.com/jsw-teams/iask/blob/main/docs/edgepress.md"
+              },
+              {
+                "label": "我提问 独立更新日志",
+                "url": "https://github.com/jsw-teams/iask/blob/main/CHANGELOG.md"
+              }
+            ]
+          },
+          {
+            "type": "code",
+            "title": "可选页面评论区块",
+            "language": "json",
+            "code": "{\n  \"blocks\": [\n    {\n      \"columns\": 1,\n      \"cells\": [\n        [\n          {\n            \"type\": \"service\",\n            \"integration\": \"github-comments\"\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "嵌入分享图片与视频",
+            "text": "在 plugins.consent.services 注册 provider: oembed 的 ishare 服务，填写实际 HTTPS backendUrl、用途与隐私披露。页面先显示本地占位，访客授权并点击加载媒体才请求服务。元数据使用固定 /api 和 HTTP 请求头传递，保留作者和来源署名的 iframe 仅使用配置的服务域名。"
+          },
+          {
+            "type": "code",
+            "title": "Pages 嵌入语法",
+            "language": "json",
+            "code": "{\n  \"blocks\": [\n    {\n      \"columns\": 1,\n      \"cells\": [\n        [\n          {\n            \"type\": \"text\",\n            \"text\": \"!embed[ishare](https://share.js.gripe/s/REPLACE_WITH_REAL_SHARE_ID)\"\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          },
+          {
+            "type": "link-list",
+            "title": "服务说明",
+            "items": [
+              {
+                "label": "ishare",
+                "url": "https://github.com/jsw-teams/ishare/blob/main/docs/zh-cn.md"
+              }
+            ]
+          }
+        ]
+      ]
+    },
+    {
+      "columns": 1,
+      "cells": [
+        [
+          {
+            "type": "text",
+            "heading": "通用社交媒体嵌入",
+            "text": "通用媒体预设仅保留 YouTube 和 X；share.js.gripe 不启用任何通用平台。自定义平台可按需在 config.yml 注册。逐项设 enabled: false 会移除授权条目和网络权限，区块保留本地未加载说明与原始链接。标准提供方使用 oembedEndpoint，构建阶段缓存元数据；浏览器必须先授权并点击加载。sourceOrigins 指定分享链接域名，embedOrigins 指定播放器与资源域名，embedScripts 是按需加载的完整脚本地址。Instagram 和 Facebook 使用公开内容的官方 iframe，不要求把 Meta 令牌放入前端；私密、禁止嵌入或平台限制的内容仍可能无法显示。Mastodon 需将默认实例替换为实际实例。"
+          },
+          {
+            "type": "code",
+            "title": "Pages 嵌入语法",
+            "language": "json",
+            "code": "{\n  \"blocks\": [\n    {\n      \"columns\": 2,\n      \"cells\": [\n        [\n          {\n            \"type\": \"text\",\n            \"heading\": \"视频与说明\",\n            \"text\": \"在播放器旁介绍内容。\"\n          }\n        ],\n        [\n          {\n            \"type\": \"text\",\n            \"text\": \"!embed[youtube](https://www.youtube.com/watch?v=jNQXAC9IVRw)\"\n          }\n        ]\n      ]\n    }\n  ]\n}"
+          },
+          {
+            "type": "text",
+            "heading": "自定义 oEmbed 与导航跳转",
+            "text": "在 config.yml 新增 provider: oembed 服务，填写授权说明、backendUrl、oembedEndpoint 与分享链接和媒体域名。公开接口不得包含密钥；需凭据的平台使用外部网关。Pages 的 text 区块与文章正文采用相同的 !embed[服务 ID](URL) 语法。导航和页脚链接含下拉选项均支持 target: _self 或 target: _blank。"
+          },
+          {
+            "type": "text",
+            "heading": "按服务配置自动生成 CSP",
+            "text": "构建会生成 Content-Security-Policy 响应头，并在 HTML 中加入适用于静态托管的同等策略。启用的服务按配置贡献脚本、连接、iframe 和媒体来源；关闭的服务不贡献网络权限。CSP 只限定网络来源，访客仍需同意后才会加载可选服务。自定义服务可增加 csp 指令映射，例如 connect-src: [https://api.example.com]，只接受 HTTPS 来源。本站上传接口等必要权限保留在源 _headers 中；GTM 容器调用额外提供方时需明确配置其域名。"
+          }
+        ]
+      ]
+    }
+  ]
+}