★ FEATURED ARTICLE 前端文档【免费下载链接】academicpages.github.ioGithub Pages template based upon HTML and Markdown for personal, portfolio-based websites.项目地址https://gitcode.com/gh_mirrors/ac/academicpages.github.io点击查看免费下载本文聚焦 academicpages.github.io 仓库中markdown_generator/目录的内容生成工具链系统讲解如何通过命令行 Python 脚本publications.py、talks.py和 Jupyter Notebookpublications.ipynb、talks.ipynb将结构化的 TSV/CSV/BibTeX 数据批量转换为站点可直接渲染的 Markdown 文件。读完本文你将掌握每种工具的输入数据格式、字段语义、命令行用法、底层实现原理以及生成结果如何被站点的 Jekyll 集合collections与页面模板消费从而搭建一条表格数据 → 站点页面的高效内容流水线。一、目录概览同一目标的两条路径markdown_generator/目录的核心使命非常明确把散落在电子表格或参考文献数据库里的结构化元数据批量转换成 academicpages 模板能够直接消费的 Markdown 文件。仓库 READMEmarkdown_generator/README.md开宗明义地指出这个目录提供了各种创建站点 Markdown 的方法。目录内所有工具按文件类型分为两大类二者功能高度对等但使用场景不同文件类型代表文件运行方式设计取向.py脚本publications.py、talks.py、pubsFromBib.py命令行如python3 publications.py publications.csv依赖极少便于在 GitHub Pages 构建环境中直接运行.ipynb笔记本publications.ipynb、talks.ipynb、OrcidToBib.ipynbJupyter 逐单元交互执行内置大量过程文档适合交互式探索与调试README 特别强调了.py脚本的设计初衷确保它们对第三方包的需求尽可能少从而可以在 GitHub 部署站点时直接运行。这一设计在源码中得到印证talks.py顶部注释明确写着 Uses the Python standard library (csv) so it has no external dependencies而publications.py同样只导入csv、os、sys三个标准库模块——这意味着你不需要pip install任何东西只要有 Python 3 解释器就能完成内容生成。从数据源角度看工具链覆盖三种输入形态TSV/CSV 表格数据publications.tsv、talks.tsv、publications.csv—— 面向出版物与演讲BibTeX 文献库pubsFromBib.py—— 面向学术出版物ORCID 在线文献记录OrcidToBib.ipynb—— 面向已关联 ORCID 账号的研究者。二、命令行脚本publications.py 出版物生成器publications.py是出版物内容生成的核心脚本其功能与文档注释markdown_generator/publications.py描述一致接收带元数据的 TSV/CSV 文件转换为 academicpages 站点可用的 Markdown。2.1 命令行用法与校验逻辑脚本只接受一个位置参数且必须是.csv或.tsv结尾的文件python3 publications.py publications.csv # CSV 输入 python3 publications.py publications.tsv # TSV 输入入口代码if __name__ __main__:执行三层校验参数个数len(sys.argv) ! 2时输出Usage: python3 publications.py [filename]并以非零码退出扩展名非.csv/.tsv文件会被拒绝提示Expected a TSV or CSV file内容行数与表头文件少于 2 行仅表头或为空时提示 Not enough lines in the file to process表头不匹配时报 The header of the file does not match the expected format。分隔符的判定在read()函数中完成文件名以.csv结尾用逗号否则用制表符delimiter , if filename.endswith(.csv) else \t因此talks.txt之类的文件也能按 TSV 规则解析。2.2 数据格式两代表头规范脚本在源码中定义了两套表头HEADER_LEGACY与HEADER_UPDATED并自动兼容HEADER_LEGACY [pub_date, title, venue, excerpt, citation, url_slug, paper_url, slides_url] HEADER_UPDATED [pub_date, title, venue, excerpt, citation, url_slug, paper_url, slides_url, category]两代格式的唯一区别是新增了category列UPDATED 版。read()会先检查首行是否等于HEADER_LEGACY等于则按旧格式处理否则要求必须完全匹配HEADER_UPDATED否则报错退出。仓库中恰好同时提供了两种格式的样例publications.tsv8 列旧格式3 条示例记录与 publications.csv9 列新格式含category: manuscripts。各字段语义与约束如下源自脚本头部文档注释与create_md()的实际处理逻辑字段是否必填约束与用途pub_date必填必须为YYYY-MM-DD格式决定文件名前缀与 permalink 中的日期段title必填写入 front matter 的titlevenue必填写入venue经 HTML 转义excerpt可空长度超过 5 个字符时写入excerpt并出现在正文描述区citation必填写入citation经 HTML 转义渲染为Recommended citationurl_slug必填文件名与 permalink 的描述性段文件名为YYYY-MM-DD-[url_slug].mdpermalink 为/publication/YYYY-MM-DD-[url_slug]paper_url可空长度超过 5 个字符时写入paperurl并生成 Download paper here 链接slides_url可空长度超过 5 个字符时写入slidesurl注意脚本新版未生成Download slides正文链接但 front matter 会保留该字段category仅新格式写入category旧格式统一回退为category: manuscripts2.3 HTML 转义YAML 兼容性的关键设计由于生成的 Markdown 头部是 YAML front matter而 YAML 对字符串中的引号非常敏感脚本定义了一张转义表HTML_ESCAPE_TABLE { : amp;, : quot;, : apos; }html_escape()函数会逐字符替换三个特殊字符。正如注释所说这让原始文件看起来不那么易读但解析后渲染效果很好。这一点在样例输出中可以直接验证2009-10-01-paper-title-number-1.md 中citation字段的值是Your Name, You. (2009). quot;Paper Title Number 1.quot; iJournal 1/i. 1(1).——双引号被转义为quot;在浏览器中会正确还原为普通引号。2.4 生成逻辑create_md() 逐行拼装create_md(lines, layout)是真正干重活的地方脚本注释原文。它遍历每一行数据依次拼装文件名与 HTML 文件名md_filename f{pub_date}-{url_slug}.mdYAML 头部依次写入title、collection: publications、category旧格式为manuscripts、permalink: /publication/{html_filename}、可选excerpt、date、venue、可选paperurl、citation正文区可选的 Download paper here 链接、可选 excerpt 文本、Recommended citation: ...落盘md_filename os.path.join(../_publications/, os.path.basename(md_filename))即输出到仓库根目录下的_publications/文件夹。值得注意的实现细节paper_url与excerpt的判空阈值是长度大于 5len(str(item)) 5这是为了过滤 NaN 之类的空值残留。三、命令行脚本talks.py 演讲与教程生成器talks.py与publications.py是同族工具但针对演讲talks场景做了独立设计且接口更灵活。3.1 命令行用法python3 talks.py talks.tsv # 输出到默认目录 ../_talks/ python3 talks.py talks.tsv _talks/ # 自定义输出目录 python3 talks.py talks.csv # CSV 输入同样支持脚本把输入文件与输出目录解耦不传输出目录时默认取脚本所在目录的上级_talksos.path.join(script_dir, .., _talks)并自动执行os.makedirs(output_dir, exist_okTrue)确保目录存在。3.2 数据格式talks.tsvmarkdown_generator/talks.tsv的完整表头为title, type, url_slug, venue, date, location, talk_url, description。仓库自带 4 条示例记录覆盖了Talk、Tutorial、Conference proceedings talk三种类型正好用来演示type字段的多样性。字段规则源自脚本实现与 talks.ipynb 的文档说明必填字段只有三个title、url_slug、date。任一缺失时脚本会打印 Skipping row: missing required field (title, url_slug, or date) 并跳过该行date必须为YYYY-MM-DD且date与url_slug的组合必须唯一——它是文件名与 permalink 的基础type为空或过短len(talk_type) 3判断时回退为默认值Talkvenue、location为空则不写入对应 YAML 字段talk_url非空时在正文生成More information here链接description非空时写入正文并经 HTML 转义。3.3 实现差异与publications.py相比talks.py有两个显著特点使用csv.DictReader按列名取值而非按索引位置代码可读性更好显式声明零外部依赖Uses the Python standard library (csv) so it has no external dependencies并统一用encodingutf-8读写对中文内容更友好。它生成的 front matter 结构可从仓库已有的生成结果验证例如 _talks/2012-03-01-talk-1.md--- title: Talk 1 on Relevant Topic in Your Field collection: talks type: Talk permalink: /talks/2012-03-01-talk-1 venue: UC San Francisco, Department of Testing date: 2012-03-01 location: San Francisco, CA, USA ---四、Jupyter Notebook 路径交互式生成流程如果更喜欢可视化、可逐步调试的工作方式publications.ipynb与talks.ipynb提供了完整交互路径。两个笔记本都遵循同一套流程模板!cat查看原始 TSV先展示数据形态并说明原始文件不美观建议用电子表格编辑import pandas as pd引入 pandas用pd.read_csv(xxx.tsv, sep\t, header0)读取数据。笔记本文档特别解释了为什么选 TSV 而非 CSV这类数据里包含大量逗号逗号分隔容易被搞乱同时提示可以替换为read_excel()、read_json()等读取其他格式定义html_escape转义函数与脚本版同一套转义表talks.ipynb版额外做了isinstance(text, str)类型判断iterrows()逐行拼装 Markdown核心逻辑与脚本版一致但publications.ipynb版还额外生成了slidesurlfront matter 字段和 [Download slides here] 正文链接并计算了year item.pub_date[:4]脚本版未使用写入../_publications/或../_talks/最后用!ls与!cat展示生成结果。笔记本内置的完整执行输出如!cat ../_publications/2009-10-01-paper-title-number-1.md的完整结果本身就是最好的教程素材可以直接对照学习 YAML front matter 的最终形态。五、BibTeX 路径pubsFromBib.py 与 OrcidToBib.ipynb5.1 pubsFromBib.py从 BibTeX 批量生成对于科研人员文献通常已经积累在.bib文件中。pubsFromBib.py 基于pybtex库实现 BibTeX → Markdown 的转换是上述 TSV 路径之外的重要补充源码注释中明确标注了 TODOMerge this with the existing TSV parsing solution。核心设计是publist配置字典按文献类型定义解析规则publist { proceeding: { file: proceedings.bib, venuekey: booktitle, venue-pretext: In the proceedings of , collection: {name: publications, permalink: /publication/} }, journal: { file: pubs.bib, venuekey: journal, venue-pretext: , collection: {name: publications, permalink: /publication/} } }每个键对应一个 BibTeX 文件venuekey指定从哪个字段取 venue会议是booktitle期刊是journalvenue-pretext是 venue 前置文本。运行前需按自己的 bib 文件名、venue 键和个性化前置文本修改该字典。处理流程for pubsource in publist:循环内用pybtex解析 bib 文件遍历每条bib_id日期归一化默认1900-01-01从year/month/day字段组装YYYY-MM-DD其中月份做了数字与英文缩写strptime(b[month][:3],%b)的兼容处理url_slug 生成对标题做{}、\、空格清理后用正则re.sub(\\[.*\\]|[^a-zA-Z0-9_-], , clean_title)剔除非法字符并合并连续--citation 自动拼装作者persons[author]的 first/last name 标题 venue 前置文本 venue 年份YAML 生成title、collection、permalink、可选excerpt来自 bib 的note字段、date、venue、可选paperurl来自 bib 的url字段、citation正文生成有note则输出有url则输出Access paper here{:target_blank}否则输出一条指向 Google Scholar 搜索的兜底链接异常处理缺字段的条目捕获KeyError打印WARNING Missing Expected Field ...并跳过不中断整体流程。5.2 OrcidToBib.ipynb从 ORCID 拉取文献OrcidToBib.ipynb 是流水线的数据获取前端它调用 ORCID 公共 APIhttps://pub.orcid.org/v3.0/{orcid}/works请求头Accept: application/orcidjson列出某 ORCID 账号的全部作品收集每个作品的put-code再逐条请求/{orcid}/work/{put-code}端点取回完整引文信息work[citation][citation-value]最后把所有引文写入output.bib。生成的.bib再交给pubsFromBib.py消费即可打通ORCID → BibTeX → 出版物 Markdown的完整链路。六、生成结果如何被站点消费理解生成器的价值需要看到它在整个站点模板中的位置——生成器输出的 Markdown 正是 Jekyll 集合与页面模板的输入。6.1 集合collections定义_config.yml 中声明了四个集合其中publications与talks与生成器直接对应collections: publications: output: true permalink: /:collection/:path/ talks: output: true permalink: /:collection/:path/output: true意味着_publications/与_talks/下的每个 Markdown 文件都会渲染为独立页面。同文件后半段的defaults配置为publications类型指定layout: single为talks类型指定layout: talk并统一开启author_profile与share。6.2 归档页如何取用生成数据_pages/publications.html 展示了生成数据在归档页的两种消费方式若_config.yml中定义了site.publication_category则按post.category分组为每个分类渲染独立标题区块这正是新表头category字段的用武之地否则直接{% for post in site.publications reversed %}遍历全部出版物通过archive-single.html渲染列表项。_pages/talks.html 则更简单{% for post in site.talks reversed %}遍历_talks/下所有生成文件用archive-single-talk.html渲染若_config.yml中talkmap_link: true还会在页首追加 talkmap 地图入口链接。6.3 单页模板_layouts/talk.html会渲染page.talk_type、page.venue、page.location、page.date等字段——这些正是talks.py写入 front matter 的键名字段命名的一致性保证了生成文件无需任何手工改动即可被模板正确展示。七、选型建议与工作流总结结合 README 说明与源码实现可以给出如下选型参考场景推荐工具理由本地批量生成出版物python3 publications.py publications.tsv零依赖、可脚本化、自动校验表头本地批量生成演讲python3 talks.py talks.tsv零依赖、支持自定义输出目录、缺字段自动跳过交互式探索与调试publications.ipynb/talks.ipynb单元格可视化、内置文档与示例输出已有 BibTeX 文献库pubsFromBib.py自动生成 citation 与 url_slug有 ORCID 账号OrcidToBib.ipynb→pubsFromBib.py全自动拉取并转换最小可行工作流用电子表格维护publications.tsv或talks.tsv→ 保存为 TSV → 在markdown_generator/目录执行对应 Python 脚本 → 检查_publications/或_talks/下新生成的.md文件 → 提交仓库GitHub Pages 构建时由 Jekyll 自动渲染为出版物/演讲页面。整个过程不需要安装任何第三方 Python 包也不需要手工编写任何 front matter。最后提醒两点使用边界一是publications.py的category是 9 列新表头才支持的字段旧 8 列格式会统一回退为manuscripts二是pubsFromBib.py依赖pybtex第三方库且publist字典需要按自己的 bib 文件调整与零依赖的 TSV 脚本适用场景不同。按需选择即可把内容维护的重心从手写 Markdown转移到维护一张干净的表格上。赞分享前端文档【免费下载链接】academicpages.github.ioGithub Pages template based upon HTML and Markdown for personal, portfolio-based websites.项目地址https://gitcode.com/gh_mirrors/ac/academicpages.github.io点击查看免费下载相关推荐academicpages 演讲Talks页面实战指南从 Front Matter 字段到批量生成与地图展示academicpages 演讲Talks页面实战指南从 Front Matter 字段到批量生成与地图展示 本指南围绕 \_talks/2012 03前端文档Jupytext 实战指南把 Jupyter Notebook 变成可版本控制的 Markdown、Python 与 R 文本文件Jupytext 实战指南把 Jupyter Notebook 变成可版本控制的 Markdown、Python 与 R 文本文件 Jupytext 是一个让开发工具使用 SumatraPDF 内置的 mutool create从内容流脚本批量生成 PDF使用 SumatraPDF 内置的 mutool create从内容流脚本批量生成 PDF 导读 mutool create 是 MuPDF 工具集中用于“从桌面应用文档上一篇RxJSv4expand 操作符完全指南递归展开 Observable 的源码剖析与实战下一篇MXNet 符号式执行引擎 executor 模块全解析Executor 绑定、前向/反向传播与参数管理实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
