Matt-17/Wotsup.org

# Wotsup.org [](https://github.com/Matt-17/Wotsup.org/actions/workflows/pr-check.yml) [](https://github.com/Matt-17/Wotsup.org/actions/workflows/jekyll-build.yml) **线上站点：** [wotsup.org](https://wotsup.org/) **浏览：** [扩展名](https://wotsup.org/extensions/) | [使用说明](https://wotsup.org/how-to/) | [贡献指南](https://wotsup.org/contributing/) | [GitHub actions](https://github.com/Matt-17/Wotsup.org/actions) Wotsup.org 是一个静态的文件格式规范及相关实现参考目录。该仓库以 Markdown/YAML 格式保存人工编写的目录，并生成 Jekyll 页面、数据文件以及线上站点使用的可下载文件树。 ## 当前工作流状态 - **PR 构建检查** 在针对 `master` 分支的 pull request 上运行。它会验证目录 schema、审计目录、检查生成输出的完整性、构建生成的页面、运行 `jekyll doctor`、构建 Jekyll 站点，并运行 `bundler-audit`。 - **部署到生产环境** 在推送到 `master` 分支时运行。它会验证目录、在启用最新更新的情况下运行生产生成器路径、构建 Jekyll 站点、打包 `src/_site/`，并使用配置的 GitHub Actions secrets 进行部署。 - 在发起 pull request 之前，本地开发应当与 PR 工作流保持一致。当您修改目录数据、生成器代码、布局或依赖项时，请使用[验证](#validation)中的命令。 ## 仓库布局 - `catalog/categories.yaml` 是规范的类别列表。 - `catalog///index.md` 包含每个手动编写的扩展名条目，使用 YAML front matter 以及可选的 Markdown 正文内容。 - `catalog///*` 可能包含通过 front matter 中的 `file:` 引用的附加规范文件。 - `src/` 包含 Jekyll 站点：布局、包含文件、样式、静态页面和生成的数据。 - `tools/` 包含基于 PowerShell 和基于文件的 C# 生成器和验证器。 - 生成的输出会写入 `src/_data/`、`src/extensions/`、`src/categories/`、`src/letters/`、`src/files/` 和 `src/_site/`。请勿手动编辑生成的文件。 ## 前置条件 - .NET SDK 10.x，用于 CI 使用的基于文件的 C# 工具。 - Ruby 3.3 与 Bundler，用于 Jekyll。 - PowerShell 7+，用于 `tools/*.ps1` 脚本。 在 Jekyll 项目目录中安装 Ruby 依赖项： ``` cd src bundle install cd .. ``` ## 快速开始 ``` # 从 repository root ./tools/build.ps1 cd src bundle exec jekyll serve ``` 服务器启动后，打开 [http://localhost:4000](http://localhost:4000)。 ## 目录工作流 1. 在 `catalog///index.md` 下编辑或添加扩展名条目。 2. 保持类别名称为小写，并与 `catalog/categories.yaml` 保持一致，例如 `archive`、`data-format` 或 `gis-formats`。 3. 将附加规范或参考文件放在条目旁边，并在 front matter 中使用 `file: filename.ext` 引用它们。 4. 使用 `./tools/build.ps1` 运行生成器。 5. 在提交之前验证生成的输出。 条目示例结构： ``` --- overview: ".zip is used for ZIP archives and ZIP-based container formats." extensions: - name: "ZIP Archive" description: "Compressed archive and package container format." categories: - archive author: "PKWARE Inc." link: "https://example.com/spec" --- ## ZIP Archive Add concise notes, identification details, compatibility notes, and references here. ``` ## 构建命令 ``` # 移除生成的 data、pages、复制的文件以及 Jekyll output ./tools/clean.ps1 # 重新生成 catalog data、pages、letters 和 site stats ./tools/build.ps1 # Production-style 生成，包括较慢的 recent-updates data ./tools/build.ps1 -IncludeUpdates # 构建静态 Jekyll site cd src bundle exec jekyll build ``` ## 验证 除非另有说明，请在仓库根目录下运行这些命令： ``` dotnet tools/validate_yaml_schema.cs dotnet tools/validate_catalog.cs ./tools/build.ps1 ./tools/check_generated_integrity.ps1 git diff --check ``` 对于布局、依赖项或生产路径的更改，还需运行： ``` cd src bundle exec jekyll doctor bundle exec jekyll build bundle exec bundler-audit check --update ``` ## 安全提示 请勿提交部署凭证、本地 secrets 或生成的部署包。生产部署使用 GitHub Actions secrets 和仓库变量；本地配置应仅限于 .NET、Bundler 和生成的构建输出。

标签：AI合规, Jekyll, 多人体追踪, 技术文档, 数据结构, 文件格式, 防御加固, 静态站点