使用Asciidoc製作學術個人主頁｜App+1

本文就使用 Asciidoc 製作網頁給出其中一個方向，Asciidoc 可用於製作大多數的簡單類別網頁。

贊助商廣告

在科研圈沉浸得越久，你會有越來越多的積累，這時候你就需要一個個人主頁來展示自己的成果，吸引學生，吸引合作和交流。大部分的科研工作者們都有自己的個人主頁，學術個人主頁還是以內容為主的網站，樣式其實沒有這麼重要。所以很多學者更注重內容的填充，鮮少有精力去折騰一個美觀漂亮的網站，這點在老教授的網站上風格尤為明顯。

MIT 學校任意找的一個老教授的個人主頁

然而，這些學術風的網站往往使用一些舊工具來製作，其生成的網站往往缺少對現代設備和功能需求的支持，如「響應式布局」，導致在手機平板等終端上閱讀比較困難。

本文將介紹一個新的標記性語言 Asciidoc 用於製作學術個人主頁，彌補上述的不足，且同時不需要太多的學習和更新負擔。

效果圖展示，內容由 AI 生成

製作學術個人主頁的方案

▍Markdown 方案的優勢與不足

學術個人主頁也是一個內容為主的網站，因為它離不開內容網站最基本的一些內容要素：標題、段落、有序列表、無序列表、引用、圖片、超鏈接等。同時，為了讓讀者更好地捕捉關鍵內容，一般需要增加文字基礎樣式，如加粗、斜體、下劃線等。這些內容的編寫和管理都非常適合使用標記性語言。

Markdown 是目前最廣為人知的標記性語言，其簡潔的語法深得大眾的喜歡。Markdown 轉化為 HTML 後瀏覽器默認的布局為全部左對齊和圖片拉伸全螢幕寬度，這對於內容網站的內容部分是比較滿足需求的，但對於製作網站整體來說是欠缺的。

比如，對於學術個人主頁來說，一般來說會放上一張自己的照片以供認識，但無論是左對齊還是拉伸全螢幕都會顯得不太合適。另一方面，Markdown 對於 HTML 元素的支持也是不足的，但是這個元素對於網站被搜尋引擎索引成功起關鍵的作用，而學術個人主頁對搜尋引擎的索引有著強烈的需求。

贊助商廣告

Markdown 的語言設計傾向於簡潔，本身只會做 markdown 標記到 html 標籤這一層語義轉化，不會產生額外的 css 排版。至於最終渲染後的樣式，完全取決於瀏覽器渲染的默認行為。因此如果想要使用 markdown 製作一個完備的網站，一般還需要藉助靜態網站生成器（如 Hugo、Hexo 等），配合一個主題（包含 css 樣式表），才能完成。而這一般需要用戶學習靜態網站生成器的使用和 css 排版系統和樣式語法等知識，對教授們來說是一個很大的挑戰。

來源 / markdowntohtml.com

▍Asciidoc 方案的異同

Asciidoc 同樣是一門標記性語言。對比 Markdown，Asciidoc 的語法略有不同，但 Asciidoc 語法也是比較簡潔的。下圖節選了一些常用的 Markdown 語法作為對比，可以看到，AsciiDoc 對比 Markdown 在樣式標記上有很大的相似性，在功能標記上增強了很多。

來源 / asciidoctor.org

雖然 Asciidoc 相對小眾，網路上的文章資源相對少一些。但實際使用主要對照官方參考文檔來寫，很快便能上手。儘管使用 Asciidoctor 作為生成器的時候可以兼容 Markdown 語法，從我個人的角度來說並不建議。使用優秀的編輯器也能提供良好的語法高亮，因此不必太擔心剛上手的時候很困難。

贊助商廣告

來源 / asciidoc.org

儘管學習 Asciidoc 會花費一點成本，但能獲得最直接的回報便是 Asciidoc 生成的網站樣式自帶的「響應式布局」（如上圖的示例圖所示）。相比大部分的 Markdown 渲染器默認的占據全螢幕寬度的做法，Asciidoc 渲染的網站能夠在大螢幕上保持內容合適寬度的居中布局。

除了原生的響應式布局優勢外，Asciidoc 引入更多的語法標記，能夠讓用戶僅使用簡單易學的標記去主動控制 HTML 元素的樣式。額外的標記包括但不限於基礎的樣式增強，文字的上下標，表格的標題，引用的出處等。

部分代表性樣式節選來自：https://asciidoclive.com

還有包括一些常用的高級語法，在需要的時候能夠產生很大的幫助。比如注釋，圖片的大小參數，影片的支持，原生字體圖標庫，摺疊段落等。這裡僅展示部分較為常用的語法示例供參考，更多的標記選項和詳細的效果建議參考文末手冊探索。

// Comment is available in asciidoc.

[.text-center]
這段文字會居中

image:https://i.imgur.com/AEkqoRn.jpg[,width=128,height=128]

video::th_H1gixMEE[youtube]

pass:[]

[%collapsible]
====
This content is only revealed when the user clicks the block title.
====

另一方面，Asciidoc 也能恰好滿足製作學術個人主頁相關的一些強烈需求，讓學者僅需要關注編寫標記性語言文檔，不必花費學習生成網站的額外配置。

左右分欄布局

放置個人照片最理想的情況應該還是傳統的左右分欄布局，Asciidoc 原生支持分欄布局。在上述的例子中，只需要在圖片的標記中加入 role=left 即可生成左右布局。

image:https://placehold.co/200x200[Placeholder,200,200,role=left]

== *San Zhang*

Title
Institute
Email (personal): [email protected]
Email (work): [email protected]

搜尋引擎索引

給搜尋引擎做適配，在網站開發的術語裡叫「SEO 優化」，對於靜態網站來說，最簡單直接的方法應該就是給 HTML 網頁里的欄位加上相應的屬性。Asciidoc 里有相應的標記去渲染成標籤里的對應元素。

贊助商廣告

:title: Zhang San
:author: Zhang San
:description: This is a personal academic homepage.

最後將部署好的網站鏈接提交給搜尋引擎，過一段時間，你將能在搜尋引擎里搜到自己的主頁並且帶有相應的欄位內容了。

文件內容復用

復用文件內容最主要的一個應用是製作一個導航欄，一個豐富的個人學術主頁不會只有一個頁面，但提供一個導航欄能方便讀者在不同內容之間跳轉。理想情況下，我們希望只製作一個導航欄，然後嵌入到不同的頁面中去，每次修改導航欄的內容，都能在不同頁面中產生變化。在 Asciidoc 中可以使用 include 標記嵌入另一份 adoc 文檔。

// header.adoc

[frame=none, grid=rows, cols="5,5,6,7,7,5,5"]

// index.adoc
include::header.adoc[]

如果還是對樣式還是有更多的追求的話，也可以選擇直接嵌入 HTML 格式的導航欄。而舉一反三，表格也可以用來製作簡單的分欄布局，在沒有高級 css 排版系統之前，舊時網頁都是無邊框表格來進行分欄布局的。

郵箱防爬蟲

很多學者們的主頁上郵箱地址都會寫成這樣的格式email: their [at] institution [dot] com，這個的目的主要是為了防止郵箱地址被網路爬蟲抓取然後接收太多的垃圾郵件。現代的防禦方法有一個很簡單有效的方式就是使用 HTML 注釋和 CSS 語法來保護地址不容易被普通爬蟲直接識別郵箱地址格式。

對於標記性語言來說，這需要同時支持 HTML 和 CSS 混合使用才能應用這一小技巧，從而方便讀者聯繫。Asciidoc 正好滿足這一需求。

// refer: https://css-tricks.com/how-to-safely-share-your-email-address-on-a-website/
Email (personal): PLEASE GO AWAY! [email protected]
Email (work): PLEASE GO AWAY! [email protected]

渲染出來的效果如上面的示例圖所示，對於人類閱讀來說沒有影響，但是對於爬蟲來說增加了很多的困難。

贊助商廣告

網站訪問追蹤

很多學者都希望關注自己的研究被哪些地區的人們訪問了，因此網站訪問追蹤是一個需求。追蹤工具一般要求支持 Javascript 的注入。Asciidoc 支持 passthrough 的功能，可以輕而易舉地使用 HTML 全部的標籤。

舉一反三，你也可以往裡面填寫標籤，這對於直觀展示一些研究項目有極大的幫助。

▍從 Asciidoc 生成網站

由於 Asciidoc 也是標記性語言，很多輕量級的工具都能將其轉換為 HTML 靜態文檔。這裡簡單列舉幾種常見的工具，大家可以根據自己的需求探索選擇合適的。比如