简介这份《数字人文作品集 Rubric1》PDF文档是田纳西大学数字人文研究生证书课程使用的作品集评估标准原文面向准备提交证书作品集的研究生、课程负责人及数字人文项目指导教师。它解决的是作品集如何组织、展示与评分的问题涵盖公共网站呈现、项目多样性、技术应用与创新、内容质量、呈现与交流等维度并附1分不可接受至4分优秀的评分系统。资源包仅含1个PDF文件约109KB轻量便于查阅和打印适合作为课程要求对照或评分参考。文档同时说明作品集需覆盖每门DH课程的代表项目、明确个人贡献、标注引用来源并鼓励参与年终展示论坛。已有82人学习读者可据此核对作品集是否完整、技术路径是否多元、反思叙述是否到位也可用于院系设计评审表或指导学生自查。1. 数字人文作品集卡在 Rubric 上的真实原因很多人做数字人文作品集时默认「网站好看分高」交了才发现视觉呈现只占一两成大头压在研究问题清不清晰、数据来源可不可追溯、方法别人能不能复跑。田纳西大学数字人文研究生证书课程的那份 Rubric1就是一份把人文研究规范和数字化交付绑在一起的检查表。它不问用了什么框架只问这份作品集作为研究产出站不站得住有研究问题、有语料、有标注或编码过程、有解释、有持久可访问的地址。对工程师来说熟悉的是构建部署和版本控制陌生的是「为什么这个可视化不能只是炫技」。下面按读懂评分维度、搭站点骨架、处理 TEI/IIIF/PDF 这几块硬骨头、做提交前自检的顺序走。新手能照着做熟手重点看参数和排错那两章。2. 拆解 Rubric1 的评分维度把研究论证翻译成可检查项一份评分表最怕被当成作文题。真正可操作的做法是把每个维度的措辞拆成「评审看什么」和「我能留下什么技术证据」后者是你能提前自证的部分。2.1 数字人文作品集的三层结构数字人文作品集通常是三层叠起来的理解这点比记评分表更重要。论证层是研究问题、方法选择、证据链和结论数据层是语料、转录、编码、元数据、授权状态、版本快照呈现层是站点、可视化、无障碍、持久链接。评审读你的作品集时视线是按论证层 → 数据层 → 呈现层走的但打分时的权重往往是倒过来的错觉呈现层最显眼分数占比却最低。常见的失败模式是这三层脱节论证层写「分析 19 世纪书信中的迁徙网络」数据层却只有一张没有出处的 CSV呈现层放了一张漂亮的地图。评审会直接问CSV 从哪来、转录规则是什么、地名如何归一化。答不上来论证层那一栏就悬了。2.2 评分维度与可执行检查的映射把 Rubric 的抽象措辞落到具体命令和文件上是整篇文章里最省时间的一步。Rubric 维度评审实际在看什么可留下的技术证据检查手段研究问题与论证问题是否具体、是否可证伪首页 research statement、分章导航人工通读限时三分钟能否说清数据来源与授权语料出处、版权状态sources.yaml、license 字段、引用页脚本校验必填字段非空方法与可复现性别人能否照着跑出同样结果Makefile、依赖锁文件、处理脚本make all从零跑通元数据与可发现性是否被检索和引用Dublin Core、JSON-LD、sitemap结构化数据校验器呈现与无障碍语义结构、对比度、替代文本语义标签、alt、跳转链接pa11y / axe过程留痕工作是不是持续做的commit 历史、tag、变更日志git log --stat这张表可以直接抄进项目根目录的README.md每完成一项就打勾。注意最后一栏过程留痕在不少评分表里是被低估的加分项因为它是唯一能证明「这不是最后一周赶出来的」的客观数据。2.3 元数据字段落位Dublin Core 与 front matter 的对应元数据不是装饰。数字人文项目里它承担三件事让作品可被检索、让来源可被追溯、让机器能理解版本关系。常见的做法是在每个作品条目里用 YAML front matter 声明元数据构建时再映射到 Dublin Core 或 schema.org。下面是一个条目示例# content/works/letters-1890.md title: 1890 年代书信中的迁徙路径 date: 2024-11-02 dcterms: creator: Your Name contributor: [档案室 A, 档案室 B] source: Box 12, Folder 3 rights: CC-BY-4.0 language: zh-Hans type: Dataset spatial: Knoxville, TN temporal: 1890/1899 method_summary: OCR 人工校对 地名归一化到 GeoNames ID reproduce: make corpus make map字段说明dcterms.type建议用 Dublin Core 的 DCMI Type 词表取值Dataset、Text、Image、InteractiveResource 等不要自造spatial和temporal是元数据里最容易被漏掉的两项也是评审判断「你知不知道自己材料的边界」的直接依据reproduce字段写一行命令比在正文里写三页方法描述管用。source要写到文件夹级别而不是「某某档案馆」。数字人文评审对出处颗粒度很敏感写到 Box/Folder 级别会立刻显得专业。2.4 用 Git 历史作为过程证据评分表里如果出现「项目发展过程」「迭代」这类字眼它能被验证的唯一形式就是提交历史。别在最后一天把整个项目一次性推上去。我一般会这样组织先用一次提交固定目录骨架和 README之后按数据、处理脚本、可视化、文档分开提交每个阶段性成果打一个 tag。# 查看提交粒度是否均匀避免一次性大提交 git log --prettyformat:%h %ad %s --dateshort # 看每个阶段改了多少文件判断过程是否连续 git log --stat --since3 months ago | head -60 # 打阶段标签方便评审定位版本 git tag -a v0.3-corpus-cleaned -m 语料校对完成地名归一化到 GeoNames参数说明--prettyformat里的%ad配--dateshort输出简洁日期方便一眼看出提交是否集中在几天内--since用来圈定课程周期git tag -a创建带说明的附注标签比轻量标签多一条可追溯的元数据。如果确实前期没规划补救办法是写一份CHANGELOG.md按日期说明每一步做了什么、为什么改。它不如真实提交历史有力但比没有强。3. 用静态站点生成器搭田纳西大学数字人文证书课程的作品集骨架静态站点是这个场景的默认选择构建产物是纯文件十年后还能打开不需要维护数据库也能整包交给图书馆归档。Hugo 和 Jekyll 都常见Hugo 构建快、模板灵活适合条目多的作品集。3.1 目录结构与最小可运行基线先定结构再写内容。结构混乱的作品集后面加元数据和无障碍都会加倍痛苦。portfolio/ ├── config/_default/hugo.toml ├── content/ │ ├── _index.md # research statement │ ├── works/ # 每个作品一个条目 │ ├── data/ # 数据集说明页 │ └── about.md ├── data/ │ └── sources.yaml # 语料与出处清单一处维护 ├── static/ │ ├── iiif/ # IIIF 清单 │ └── files/ # 可下载的 PDF、CSV ├── layouts/ │ ├── _default/single.html │ └── partials/schema.html # JSON-LD 注入 ├── scripts/ │ └── check.py # 提交前自检 └── Makefilesources.yaml单独抽出来的理由是出处信息会同时出现在条目页、引用页和 PDF 里一处维护能避免三处不一致。评审如果发现同一个语料在三个地方写法不同会直接怀疑数据可靠性。3.2 Hugo 建站与本地预览的命令与参数从零到能在浏览器里看到东西命令不多但参数值得记清楚。# 初始化站点 hugo new site portfolio --force # 新建一个作品条目自动带上 front matter 模板 hugo new content works/letters-1890.md # 本地预览-D 显示草稿--bind 让容器或局域网可访问 hugo server -D --port 1313 --bind 0.0.0.0 --disableFastRender # 正式构建压缩输出生成 sitemap hugo --minify --gc --baseURL https://example.org/portfolio/参数说明-D只影响本地预览不会把草稿发到线上--disableFastRender在改模板时更稳避免页面局部不刷新造成误判--gc清理无用缓存资源--baseURL在正式构建时必须显式指定否则生成的绝对链接会指向localhost而这点在本地几乎看不出来上线后才炸。提示baseURL写错最常见的症状是 RSS、sitemap 和 JSON-LD 里的地址全是本机地址。构建完先grep -r localhost public/扫一遍。3.3 结构化数据注入让作品集真正被检索到元数据只写在 front matter 里只有站内能看见。要让搜索引擎和聚合平台理解条目得在页面里输出 JSON-LD。!-- layouts/partials/schema.html -- {{ with .Params.dcterms }} script typeapplication/ldjson { context: https://schema.org, type: {{ .type | default CreativeWork }}, name: {{ $.Title | jsonify }}, creator: { type: Person, name: {{ .creator | jsonify }} }, datePublished: {{ $.Date.Format 2006-01-02 | jsonify }}, license: {{ .rights | jsonify }}, inLanguage: {{ .language | jsonify }}, spatialCoverage: {{ .spatial | jsonify }}, temporalCoverage: {{ .temporal | jsonify }}, isBasedOn: {{ .source | jsonify }} } /script {{ end }}这段模板的逻辑是只有条目的 front matter 里存在dcterms才输出脚本避免空字段污染结构化数据。jsonify负责转义别手写引号标题里出现引号或换行会直接让 JSON 失效。type给一个默认值是因为 schema.org 的校验器对类型缺失比较敏感。构建完用一行命令抽检页面上有没有合法的 JSON-LD# 从构建产物里提取 JSON-LD 并用 python 校验语法 grep -o script typeapplication/ldjson.*/script public/works/*/index.html \ | sed s/[^]*//g | python3 -m json.tool /dev/null echo JSON-LD OK3.4 构建与发布流水线GitHub Actions 最小配置自动化构建的意义不只是省事它能让「可复现」这件事有客观记录。评审点开仓库能看见每次构建都通过比任何描述都直接。# .github/workflows/build.yml name: build-portfolio on: push: branches: [main] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: submodules: recursive # 主题作为子模块时必须开 - uses: peaceiris/actions-hugov3 with: hugo-version: latest extended: true # 用到 SCSS 处理时需要 extended - run: make check # 元数据、断链、无障碍自检 - run: hugo --minify --gc --baseURL https://example.org/portfolio/ - uses: actions/upload-pages-artifactv3 with: path: ./public参数说明submodules: recursive是主题用 git submodule 引入时最容易踩的坑漏了会构建出一个没有样式的裸页面extended: true只在需要处理 SCSS/SASS 时才要普通项目可以省make check放在构建之前是让数据问题先失败而不是等页面生成完才发现。4. 数字人文项目的三类技术排错TEI、IIIF 与 PDF 交付到这里站点骨架已经能跑剩下的问题几乎全在格式上。数字人文用到的格式不算多但每一个都有自己的脾气出错信息还偏晦涩。4.1 TEI XML 校验与高频命名空间错误TEI 是文本编码的通用方案作品集里通常用来展示转录成果。手写 TEI 几乎一定会出问题所以校验步骤要固定下来。# 结构良好性检查最快先过这一关 xmllint --noout transcript.xml # 用 TEI 官方 Relax NG 模式做完整校验 xmllint --noout --relaxng tei_all.rng transcript.xml # 只看错误行号便于批量修 xmllint --noout --relaxng tei_all.rng transcript.xml 21 | grep -o line [0-9]* | sort -u参数说明--noout表示不回显 XML 内容只报错--relaxng指定模式文件TEI 的模式文件通常叫tei_all.rng需要从 TEI 官方发布包中取得别自己拼。三条命令的顺序建议固定先结构、再模式、最后批量统计。高频错误有三类。第一类是命名空间没写根元素必须带xmlnshttp://www.tei-c.org/ns/1.0漏了会报一大堆「元素未知」。第二类是xml:id重复尤其是复制粘贴一个persName段落时最容易发生改掉即可。第三类是元素嵌套顺序TEI 对teiHeader内部的子元素顺序有硬性要求fileDesc必须在encodingDesc之前。这类错误的报错信息只会说「元素 X 在此处不允许」不会告诉你正确顺序得回去查模式定义。注意把 TEI 文件直接cat进 HTML 模板里展示是常见错误做法。先做 XSLT 或 Python 转换输出干净的 HTML 片段再交给模板渲染否则浏览器会把命名空间当成未知标签处理。4.2 IIIF 清单手写起步与图像查看器接入作品集里放图像尤其是手稿、地图、照片用 IIIF 是行业惯例因为查看器可缩放、可对比、可被别人复用。清单文件手写一份最小可用的比从零学整套 API 快。{ context: http://iiif.io/api/presentation/3/context.json, id: https://example.org/iiif/manifest-1, type: Manifest, label: { zh-Hans: [1890 年手稿第 1 页] }, items: [ { id: https://example.org/iiif/canvas/1, type: Canvas, height: 1200, width: 1600, items: [ { id: https://example.org/iiif/canvas/1/page, type: AnnotationPage, items: [ { id: https://example.org/iiif/canvas/1/annotation, type: Annotation, motivation: painting, body: { id: https://example.org/iiif/image/1/full/max/0/default.jpg, type: Image, format: image/jpeg, height: 1200, width: 1600 }, target: https://example.org/iiif/canvas/1 } ] } ] } ] }字段说明type必须是Manifest且每个层级的type都不能省这是 IIIF 3.0 最常出错的地方label用语言映射对象而不是裸字符串方便多语种Canvas 的宽高要与图像实际像素一致写错了查看器会画偏图像服务地址末尾的/full/max/0/default.jpg是 IIIF Image API 的固定路径段顺序不能换。清单写好后放进static/iiif/页面里引入查看器script src/js/openseadragon.min.js/script div idviewer stylewidth:100%;height:600px/div script // tileSources 指向 IIIF 清单查看器会自动解析 canvas OpenSeadragon({ id: viewer, tileSources: /iiif/manifest-1.json, prefixUrl: /js/images/, showNavigator: true, // 多页手稿建议开导航缩略图 sequenceMode: true // 清单含多个 canvas 时开启连续浏览 }); /script参数说明sequenceMode只有在清单含多个 Canvas 时才有意义单页开了会看到多余控件showNavigator对大幅地图和手稿很有用但对小尺寸图片是负担。4.3 无障碍与 PDF 交付从 HTML 到可提交文件评分表里「呈现」那一栏无障碍通常单列。检查用命令行就够不必装浏览器插件。# 对本地预览或构建产物做 WCAG2AA 检查 pa11y http://localhost:1313/works/letters-1890/ --standard WCAG2AA # 批量检查内链和外链 lychee --no-progress ./public/**/*.html参数说明--standard WCAG2AA指定标准等级课程类评分表一般按 AAlychee扫构建产物而不是源文件因为最终交付的是 HTML。常见失败项集中在三处装饰性图片没写alt写了空串是对的完全不写是错的、对比度不足、跳转链接缺失。如果评分表要求提交 PDF不要用浏览器「打印为 PDF」草草了事。那样的文件没有标签结构、没有阅读顺序屏幕阅读器读出来是一团乱。# 用 weasyprint 从 HTML 生成带结构信息的 PDF weasyprint index.html output.pdf \ --base-url ./ \ --pdf-variant pdf/a-3b # 校验 PDF 结构完整性 qpdf --check output.pdf # 严格模式校验暴露元数据和结构问题 pdfcpu validate -mode strict output.pdf参数说明--pdf-variant pdf/a-3b输出归档级 PDF适合长期保存也是不少图书馆的接收要求--base-url决定相对路径资源的解析基准漏了会导致图片丢失qpdf --check只看结构是否损坏pdfcpu validate -mode strict检查更细两者互补。生成后务必用阅读器打开确认标题层级、书签和替代文本是否保留这些在自动化检查里查不出来。5. 让 Rubric 评分可复现自检脚本与交付前的最后三个动作评分表最怕「我以为是加分项其实评审没看见」。解决办法是把能自动化的检查都自动化跑一次脚本输出的就是一份自证清单。# scripts/check.py —— 提交前自检返回非零表示有问题 import sys, re, pathlib, yaml REQUIRED [title, date, dcterms] DCTERMS [creator, source, rights, type, language] errors [] for md in pathlib.Path(content/works).glob(*.md): text md.read_text(encodingutf-8) m re.match(r^---\n(.*?)\n---, text, re.S) if not m: errors.append(f{md}: 缺少 front matter) continue fm yaml.safe_load(m.group(1)) or {} for k in REQUIRED: if k not in fm: errors.append(f{md}: 缺字段 {k}) for k in DCTERMS: # 元数据必填项逐个检查 if not (fm.get(dcterms) or {}).get(k): errors.append(f{md}: dcterms.{k} 为空) # 检查图片是否都有 alt 属性 for html in pathlib.Path(public).rglob(*.html): for tag in re.findall(rimg[^]*, html.read_text(encodingutf-8)): if alt not in tag: errors.append(f{html}: 图片缺 alt - {tag[:60]}) print(\n.join(errors) if errors else check passed) sys.exit(1 if errors else 0)逻辑说明脚本只做三件确定性判断——必填字段是否存在、Dublin Core 核心项是否为空、图片是否有alt。之所以不做模糊校验比如判断「研究问题写得好不好」是因为那部分只能人工读。sys.exit(1)让它在 CI 里能直接卡住构建。把它接到 Makefile 上一个命令跑完全套.PHONY: check build all check: python3 scripts/check.py lychee --no-progress ./public/**/*.html hugo --minify --gc --baseURL https://example.org/portfolio/ qpdf --check public/files/portfolio.pdf build: hugo --minify --gc all: check build交付前最后三个动作按顺序做。第一关掉本地预览服务从干净目录重新make all确认没有依赖任何本机缓存或临时文件——这一步能查出「在我电脑上能跑」的经典问题。第二用无痕窗口打开构建产物键盘只用 Tab 走一遍首屏看焦点顺序是否合理、跳转链接是否第一个出现。第三翻回README.md把reproduce字段里的命令实际粘进终端跑一次确认它真的能跑出结果而不是三个月前写的备忘录。最后一个容易被忽略的细节在content/_index.md第一段用一句话写清研究问题限定在 40 字以内。评审打开首页的前十秒决定了他对你整份作品集的预期这句话比后面所有技术实现都更值钱。本文还有配套的精品资源点击获取