CrossDarkRefactor project structure and scripts for web generation

地狱之下 · 文档

地狱之下项目的 Typst 正文源码,由架空世界模板渲染,可输出 PDF 与多页网页。

PDF:发行版 —— 普通版 / 打印版 / 小屏版
网页:make web 生成多页站点 —— 首页 / 为全量文档,各章节为独立页

文件

文件	说明
`内容/index.typ`	全量单页入口(PDF 与网页 `/`)
`配置.typ`	站点配置(再导出模板、网页模板、站内导航、导航卡片清单、元素系统 CSV 路径)
`内容/<路径>.typ`	各章正文(自带 `#import "…/配置.typ": *`),路径即网页 URL 段
`内容/<路径>/index.typ`	目录页正文(如 `内容/特殊能力/index.typ` → `/特殊能力/`)
`脚本/页面.typ`	网页各独立页的统一入口(make 传 `--input 页=`、`--input 源=`)
`脚本/web_post.sh`	网页后处理(抽外部样式、跨页元素链接;纯 sh + awk)
`脚本/test.sh`	测试脚本(编译、CSV、格式规范)
`附件/元素系统.csv`	元素系统数据(宽表:首行=系统名,首列=元素 id)
`Makefile`	编译脚本(普通/打印/小屏/元素系统版/网页)

编译

# 全部 PDF(普通版 + 打印版 + 小屏版,make all 已含后两者)
make all

# 单独生成
make print
make screen

# 指定元素系统
make 元素系统 元素系统名=academic

# 网页版:完整单页 dist/index.html + 各独立页 dist/<路径>/index.html
make web

网页多页站点

路由约定

内容/<路径>.typ → /<路径>/(如 内容/生物/怪动植物.typ → /生物/怪动植物/,单级如 内容/世界纲要.typ → /世界纲要/)
内容/<路径>/index.typ → /<路径>/(目录页,如 内容/特殊能力/index.typ → /特殊能力/)
内容/index.typ → /,既是全量文档,也是站点首页 dist/index.html

页面集合 = 内容/ 目录树:构建期由 Makefile 的 web 目标扫描——内容/<路径>.typ → /<路径>/,内容/<目录>/index.typ → /<目录>/,空文件也算一页(如 内容/特殊能力/灵力.typ → /特殊能力/灵力/);每页一个 typst compile,源文件优先 内容/<路径>.typ,没有则取 内容/<路径>/index.typ。脚本/页面.typ 的页标题取路径最后一段。配置.typ 的 导航 只配导航卡片(显示哪些、顺序、名称),不定义 URL。

构建

各页共用一个入口 脚本/页面.typ,页名与源文件由 make 经 --input 页=、--input 源= 传入:

make web   # dist/index.html(全文)+ dist/生物/怪动植物/index.html + …

要点

右上角导航栏(模板参数 页脚链接)只留首页与站外链接(PDF/GitHub/GitCode);各页入口集中写在 内容/index.typ 的 #目录 前,用 #if is_web() 包裹——只在网页出现,PDF 不渲染。
站内链接与字体一律绝对路径(/webfonts/、/生物/怪动植物/),天然支持多级路由。
各页共享抽出的外部样式 dist/assets/underhell.css。
元素定义在别页时,web_post.sh 把该页的"未定义"元素重写成指向定义所在页的链接。
正文文件必须自带 #import "…/配置.typ": *(模板成员经它再导出;include 不继承父作用域)。
全量入口用 #导入("内容/生物/怪动植物.typ", 偏移: 2);这个 导入 由 配置.typ 提供, 路径相对 文档/ 解析(模板自带的 导入 以仓库根为基准)。

元素系统

元素系统通过 #元素("ID") 在文档中引用核心概念。普通系统直接返回 ID 本身,其他系统(别名、academic)从 附件/元素系统.csv 宽表中查找。

CSV 格式:首行为各元素系统名(不含普通),首列是元素 id,单元格为对应名词(空则回退到普通)。

id,别名,academic
怪物,,
怪动物,白色怪物,
怪动植物,黑白怪物,
超级系统,,生物能量超级系统
嗜血仙子,黑白仙女,
水仙子,水仙女,

只要文档中使用了 #元素("xxx"),就必须将 xxx 写入 CSV id 列。 元素文本在渲染时自动标红(深红)并使用标题字体。

#元素(id):引用某元素,渲染当前系统深红名词;该元素在文档中有标题时自动成为跳转链接。
#设定元素(id, level: none):普通模式为深红文本;传入 level 即为标题(= 标题 <id>,@id 可交叉引用)—— #设定元素(level: 2)[伪神]。文档中的章节标题均用此形式定义。
#评论(正文):标题字体、灰色注释,--input 隐藏评论=true 编译时隐藏。

未定义元素(被引用但暂无定义小节):PDF 编译给出 warning;HTML 输出(--features html --input web=true)渲染悬停弹窗"未定义"。

可运行 程序/元素工具/元素工具.py 自动补全编码/改名元素,详见程序/元素工具/README.md。

字体

通过 lang: "zh" 加载中文配置(模板/languages/zh.toml)。字体配置:

header:段宁毛笔小楷(标题 + 元素默认)
body:霞鹜文楷等宽(正文)
italic:等距更纱黑体 SC(斜体)

AI 技能

本仓库内置 AI 助手技能,描述正文写作与编译规范(编译命令、章节结构、元素系统用法、语法规范、已知编译坑):

.skills/SKILL.md