App+1 | 使用 Asciidoc 制作学术个人主页
内容提要
本文介绍了使用Asciidoc制作学术个人主页的方案。相比于Markdown，Asciidoc具有更多的语法标记和功能，可以实现响应式布局、搜索引擎索引、文件内容复用等需求。同时，Asciidoc也支持HTML和CSS的混合使用，可以防止邮箱被爬虫抓取。最后，文章列举了几种将Asciidoc转换为HTML的工具。
延伸解读
为什么学术主页需要超越 Markdown
文章指出，Markdown 虽然简洁，但默认渲染为左对齐和图片全屏宽度，不适合放置个人照片等布局需求。此外，Markdown 对 HTML <head> 元素支持不足，而学术主页依赖搜索引擎索引，需要设置 title、author、description 等元数据。若用 Markdown 构建完整网站，通常需搭配静态网站生成器和 CSS 主题，学习成本较高。Asciidoc 则原生支持响应式布局和更多语法标记，能直接控制样式，减少额外配置。
Asciidoc 如何满足学术主页的特定需求
文章列举了 Asciidoc 的几个实用特性：通过 role=left 实现图片与文字左右分栏，适合放置个人照片；使用 :title:、:author: 等标记生成 <head> 元数据，便于搜索引擎索引；利用 include 标记复用导航栏文件，修改一处即可全局生效；结合 HTML 注释和 CSS 隐藏技术保护邮箱地址，增加爬虫抓取难度；通过 passthrough 注入 JavaScript 实现访问追踪或嵌入视频。这些功能仅需编写标记文档，无需深入学习 CSS 或静态网站生成器。
转换工具与部署路径
Asciidoc 可转换为 HTML 静态文档，文章介绍了多种工具：Vscode 插件 AsciiDoc 可通过命令保存 HTML；命令行工具 Asciidoctor 支持包管理器安装；在线工具 asciidocLive 和 Chrome 插件 Asciidoctor.js Live Preview 可即时预览并保存网页。生成 HTML 后，上传到学校或学院指定目录即可发布。若倾向外部平台，可探索 GitHub Action 自动化部署。这些工具覆盖了从本地编辑到在线预览的常见场景，用户可根据习惯选择。
Q&A
为什么学术个人主页更适合用 Asciidoc 而不是 Markdown？
Asciidoc 相比 Markdown 具有更多语法标记和功能，能原生支持响应式布局、搜索引擎索引优化、文件内容复用等学术主页常见需求，而 Markdown 对 HTML <head> 元素支持不足，且默认渲染样式不适合网站整体布局。
Asciidoc 如何实现学术主页的响应式布局？
Asciidoc 生成的网站自带响应式布局，能在大屏幕上保持内容合适宽度的居中布局，不同于多数 Markdown 渲染器默认的全屏幕宽度拉伸，从而在不同设备上都有良好的阅读体验。
用 Asciidoc 制作学术主页时，如何防止邮箱被爬虫抓取？
Asciidoc 支持 HTML 和 CSS 混合使用，可以通过在邮箱地址中插入 HTML 注释和隐藏的 span 元素来混淆爬虫，例如在邮箱中插入注释或使用 display:none 的 span，从而保护邮箱地址不被普通爬虫识别。
Asciidoc 如何帮助学术主页被搜索引擎收录？
Asciidoc 提供了相应的标记来渲染 HTML <head> 中的 title、author、description 等元素，方便进行 SEO 优化，将部署好的网站链接提交给搜索引擎后，就能被搜索到并显示相应字段内容。
Asciidoc 如何实现网站导航栏的复用？
Asciidoc 可以使用 include 标记嵌入另一份 adoc 文档，例如将导航栏内容放在 header.adoc 中，然后在每个页面中通过 include::header.adoc[] 引入，这样修改导航栏内容后所有页面都会同步更新。
有哪些工具可以将 Asciidoc 转换为 HTML？
常见的工具包括：Vscode 插件 AsciiDoc（使用命令 AsciiDoc: Save HTML document）、命令行工具 Asciidoctor、在线工具 asciidocLive 和 Asciidoctor.js Live Preview（Chrome 插件），以及通过 GitHub Action 自动化部署。
