Ampio Knowledge Base

作為一家專注於為各行各業提供高度客製化智能解決方案的公司，Ampio 在多年來積累了大量的知識。我們一直在尋找一個用戶友善的平台，將這些知識傳遞給我們的客戶和安裝商。提供一個能同時滿足全球不同需求和期望的服務，對我們來說是一項挑戰。

一方面，我們需要一個能夠讓沒有技術背景的客戶以視覺化的方式了解我們系統的工具。

另一方面，我們的安裝商則需要技術圖紙、離線手冊，並深入探討高度專業的主題。

此外，我們也無法忽視一個事實，那就是我們內部的知識庫編輯和維護團隊包括許多非程式開發人員，他們必須能夠像程式開發者一樣創建內容並瀏覽網站架構。

我們開始時設立了以下需求：

  • 便於貢獻
  • 高效的搜尋功能
  • 能部署至簡單的共享主機
  • 良好的多語言支持

WordPress 的黑暗時代

考慮到上述需求，我們最初在 WordPress 上使用了一個商業的知識庫插件來建立服務。最初的需求看似不過分，但我們驚訝地發現，市面上可用的解決方案只有少數幾個能夠滿足這些需求。尤其是多語言支持，這一需求在現有的插件中似乎被忽略了。

基於 WordPress 的產品做出了大膽的承諾：花點錢，幾分鐘內就能啟動服務，並且不必再擔心開發上的麻煩。雖然這些承諾在 WordPress 層面上可能是可實現的，但對於非最簡單的部署情況來說，顯然並不適用。對我們來說，越來越多的妥協變得無法避免。而且，這些解決方案在我們為該任務專門配置的簡單共享主機環境中運行得很慢。

轉折點

轉折點來自於引入了一個新的關鍵需求——每個文檔必須能夠下載為 PDF 格式。我們所擁有的插件無法提供這個功能，市面上其他的 WordPress 插件也似乎無法滿足我們的需求。團隊中沒有人敢在現有堆疊中增加這項功能，因此我們決定重新開始。

此外，我們還必須記住另一個關鍵需求，即，服務的維護和內容創建主要由非程式開發人員負責。起初，我們傾向於使用基於 headless CMS 的解決方案，但最終我們作出了大膽的決定，創建一個由 Git 管理的 Jamstack 服務，並看看會發生什麼。

Hugo 出現

Hugo 成為我們首選的靜態網站生成器（SSG）。它對多語言的支持是我們選擇的主要原因。後來，當我們瀏覽文檔時，還發現了許多新的、令人興奮的功能，這些功能在我們開始時甚至不知道我們需要。

WordPress 的 WYSIWYG 編輯器的豐富功能很快變成了一種詛咒。在多個貢獻者準備的文檔中保持格式一致性變得很繁瑣。當我們考慮到 Markdown 時，我們知道它會給我們帶來更少的靈活性，但對我們來說，這正是一個隱藏的祝福——Markdown 的約束確保了每篇文檔的編寫方式都相同。在需要更多功能的情況下，Hugo 的短代碼給了我們所有所需的工具來達到預期效果。

在 PDF 生成方面，我們利用 自定義輸出格式 來生成中介文檔表示，然後使用我們的自定義工具將它們轉換為 TeX 文檔，最後生成 PDF 文件。

我們也利用自定義輸出格式創建了搜尋索引。搜尋功能是基於出色的 TNTSearch 函式庫建立的。搜尋查詢和結果由嵌入在 Hugo 處理的靜態文檔中的 PHP 片段處理。

我們甚至實現了一個由 Hugo 生成的簡單 REST API！到目前為止，我們還沒遇到什麼是這個堆疊無法解決的，而在基於 WordPress 的解決方案中，我們曾經為了定義自訂文檔排序這樣簡單的問題而掙扎。

談到 Hugo，我們不能忽視它的速度。一開始，我們並不認為這是殺手級的特點，但隨著文檔庫的增長，我們越來越欣賞它。乾跑（dry-runs）並不常見——大多數時間，我們處理的文檔已經在之前的 Hugo 運行中建立了快取。在這種情況下，Hugo 會在大約一秒鐘內重建網站，我們認為這是一個非常好的結果。

                   | EN  | PL
-------------------+-----+------
  Pages            | 483 | 486
  Paginator pages  |  56 |  55
  Non-page files   | 745 | 749
  Static files     | 917 | 917
  Processed images | 487 | 490
  Aliases          |  80 |  79
  Sitemaps         |   2 |   1
  Cleaned          |   0 |   0

Total in 1096 ms

貢獻者之間的適應

很快，我們發現關於貢獻者之間工作流程適應的最初擔憂過於誇張。Markdown 相當簡單，並未給貢獻者帶來麻煩。

我們建議同事們使用 Visual Studio Code 作為內容創建工具。該專案的倉庫跟蹤了專案範圍的編輯器配置，這包括一組 任務，允許從 GUI 層級運行實時伺服器。對於那些面對強大終端時容易被嚇到的人來說，這非常有用。

Git 工作流程的基本技能也很容易掌握。最終，建構和部署完全由 CI/CD 流程管理，因此服務的管理簡化為審查和接受 Git 前端的合併請求。作為副作用，我們獲得了完整且清晰的貢獻歷史，這對我們的質量保證審核員來說非常重要。

我們甚至可以說，我們的實驗在我們的組織中推廣了 Git 的使用，並且讓非程式開發人員也愛上了它！

總結

Hugo 是最棒的！如果你面臨類似我們的挑戰，一定要嘗試它。如果你的服務貢獻者並不太擅長技術，也不必擔心——它仍然有可能取得很好的效果！

Alora Labs Webpack 入門指南：前端模組打包工具