全新文件

經過幾週的努力，我很興奮地宣布 Formik 的全新文件網站及其新網域 https://formik.dev.org.tw 正式上線。

Formik 是 Facebook 文件框架 Docusaurus 的早期使用者之一。它運作良好，而且由於樣式選項有限，它幫助我們將重點放在內容而不是外觀上。

話雖如此，Docusaurus v1 仍有其缺點。首先，它是一個真正的靜態網站產生器。它會輸出純 HTML。這對許多函式庫和工具來說很棒，但對於像 Formik 這樣一個 React 套件來說，無法運行現代的客户端 JavaScript 變得令人沮喪。像是頁面內遊樂場或可編輯的程式碼區塊都無法實現。

當需要更新文件時，我評估了 Gatsby 和 Docusaurus v2，但最終決定使用 Next.js。感謝像是 `getStaticProps`、全域路由和增量靜態網站生成等新功能，Formik 文件現在擁有了堅實的基礎，我們可以在此基礎上持續創新。

太長不看版 (tl;dr)

Formik 文件使用以下工具建構：

• Next.js 9.4.x + MDX
• Notion（用於支持您正在閱讀的這篇部落格文章）
• Tailwind CSS
• 使用 Algolia DocSearch v3 Alpha 進行搜尋

本文的其餘部分將更詳細地概述 Formik 的文件堆疊、其背後的一些基本原理，以及一些您可能會覺得有趣的資訊。

Next.js 9.4

我選擇 Next.js 而非 Gatsby 和 Docusaurus v2 等替代方案，原因有幾個。決策中最大的因素是我相信文件是產品的一部分。由於我即將推出的 SaaS 儀表板和行銷網站已經使用 Next.js，因此留在 Next.js 的生態系統中意味著所有程式碼庫都將以相同的方式工作，即使是開源的程式碼庫也是如此。這減少了認知負擔，並使跨應用程式工作和共享組件變得更加容易。

為什麼不用 Gatsby？

Gatsby 是一個基於 React 的靜態網站產生器，具有豐富的插件和主題生態系統。它的主要價值主張是由 GraphQL 支持的單一數據圖。關於文件網站，Gatsby 主題（子主題可以繼承的插件、佈局和組件的組合）非常有用。鑑於我們正在開發的開源專案越來越多 (我們正在開發的專案)，這一點非常吸引人。然而，我相當確信 GraphQL 對於文件和大多數靜態文件驅動的網站來說仍然過於複雜。是的，我完全知道您在技術上並不需要在 Gatsby 中使用 GraphQL，但它絕對是它的最佳路徑。

為什麼不用 Docusaurus v2？

在撰寫本文時，Docusaurus v2.0 仍處於 alpha 階段。新版本通過允許客户端 React、插件，甚至自定義主題，解決了 v1.0 的許多問題。

對我來說，Docusaurus 2 最大的問題是它的基本主題。

對於許多專案來說，Facebook 的全新靜態 CSS 文件框架 Infima（Docusaurus 使用它，並且由同一個團隊共同開發）就足夠了。然而，它有一些地方真的困擾著我。

行動裝置導航感覺很笨拙

我在行動裝置上瀏覽每個 Docusaurus v2 網站時總是遇到困難。與 Docusaurus v1 的子導航列相比，我發現浮動子導航很不直觀。這裡有一個比較影片。v1 在左邊，v2 在右邊。

Infima CSS 不容易設定主題

雖然 Infima CSS 是一個完整的 CSS 框架，但它的主題選項有些有限。讓新的 Formik 文件在視覺上與我們企業 SaaS 應用程式的設計系統保持一致似乎也具有挑戰性，因為我們需要大幅度地調整/擴展 Infima CSS。

缺乏社群主題

Docusaurus v2 的另一個重要新增功能是自定義主題和一流的主題組件覆蓋（又稱「Swizzling」）。如果您以前從未聽說過它，組件 Swizzling 的工作方式類似於 Wordpress 的主題和插件模板層次結構，但適用於 React 組件。當您運行 `docusaurus swizzle <主題名稱> [組件名稱]` 時，Docusaurus 會將該組件從指定的 themes `node_modules` 中複製到 `src/theme/[組件名稱]` 中的本地檔案。然後，您可以對該檔案進行所有您想要的更改，Docusaurus 將在構建您的網站時使用「Swizzled」版本而不是基本版本。

Swizzling 的最大缺點與永遠困擾 Wordpress 子主題的缺點相同——它會使升級變得更加複雜（尤其是在基本主題中新增功能時）。事實上，這個問題非常突出，以至於 Docusaurus 文件目前警告不要 Swizzling，直到 v2 到達 beta 階段

我們希望盡量避免 swizzling 組件，直到我們至少達到 Beta 階段。組件 API 一直在快速變化，並且很可能會持續變化，直到我們達到 Beta 階段。如果可能，請暫時使用預設外觀，以避免將來可能遇到的麻煩。

此時，我花了一些時間評估為 Formik 編寫我們自己的自定義 Docusaurus v2 主題需要做些什麼，但最終因為上述警告而決定放棄。我的理由是，如果我要深入研究這個問題，我不妨使用 Next.js 完全控制整個 Markdown 處理流程——而這正是我所做的……

MDX 勝出 (MDX FTW)

只要稍加努力，Next.js 就可以非常適合用於文件——MDX 是其中的秘訣。然而，要使其功能與 Docusaurus 相提並論，需要付出相當大的努力，而且並非易事。話雖如此，我對新文件的運作方式、貢獻的難易度以及網站的外觀都非常滿意。

值得指出的是，Formik 的新文件處理 MDX 的方式與大多數 Next.js 網站可能略有不同。我没有使用官方的 `@next/mdx` 插件，而是厚顏無恥地從 Expo.io 文件中竊取了 Brent Vatne 的自定義 webpack loader，它會自動提取 front-matter 並在每個 .mdx 檔案中注入一個包裝器佈局組件 export。

1 const fm = require('gray-matter');
2 
3 // Makes mdx in next.js much better by injecting necessary exports so that
4 // the docs are still readable on github
5 // (Shamelessly stolen from Expo.io docs)
6 // @see https://github.com/expo/expo/blob/master/docs/common/md-loader.js
7 module.exports = async function (src) {
8   const callback = this.async();
9   const { content, data } = fm(src);
10   const layout = data.layout || 'Docs';
11   const code =
12     `import { Layout${layout} } from 'components/Layout${layout}';
13 export const meta = ${JSON.stringify(data)};
14 export default ({ children, ...props }) => (
15   <Layout${layout} meta={meta} {...props}>{children}</Layout${layout}>
16 );
17 ` + content;
18 
19   return callback(null, code);
20 };

預設情況下，此 loader 會注入 `LayoutDocs.tsx` 佈局組件作為包裝器，但可以在需要時新增其他佈局。它們可以通過 `layout` frontmatter 鍵逐頁指定。

使用 靜態網站生成 的 Notion 支持的部落格

您正在閱讀的這個部落格實際上是由 Notion 和 Next.js 的靜態網站生成功能支持的，而不是使用傳統的 CMS 或 MDX。我們將文章保存在 Notion API 中的一個表格中，其中包含相關的元數據，然後將 Notion 未公開的 API 映射到 ./src/pages/blog/[...slug].tsx 中的自定義 React 組件。結果令人驚嘆，而且寫作體驗非常棒。有關此設定的更詳細示例以及您可以立即部署的示例，請訪問：https://notion-blog.now.sh/

Tailwind

多年來，我一直是 Atomic CSS 的愛好者。Tailwind 是最新的，也許是所有 Atomic CSS 框架中最棒的。它很靈活、直觀、外觀精美，而且在效能方面無與倫比（因為它只是 CSS！）。感謝 Tailwind 1.4.x，我們現在也能使用其新的 purge 功能清除所有多餘的 class。

Algolia DocSearch v3 Alpha 版

我在製作文件時偶然發現了新版的 docsearch.js，它比我想像的還要好。它有一個很酷的 Omnibar（整合式搜尋欄），甚至可以記錄最近的搜尋和我的最愛。

總體而言，我對新的文件網站非常滿意。這是我一段時間以來第一次對撰寫文件感到興奮。雖然仍然缺少一些功能，但我對這個技術堆疊提供的終端使用者體驗和開發者體驗感到非常滿意。Next.js 為我們在文件網站中構建更多類似應用程式的功能奠定了良好的基礎。首先，我們將推出全新的互動式教學，以及新的可搜尋範例和樣板目錄。與往常一樣，如果您有興趣幫忙或深入了解，新的文件完整原始碼已在 GitHub 上公開。

話不多說，去探索看看吧，但請溫柔對待它。如果您發現任何錯誤，請提交 issue。有了這個新的 Notion 支援的部落格，我會更頻繁地發佈文章，所以在頁尾輸入您的電子郵件，然後按下訂閱按鈕加入 Formik 郵件列表。

-J

2021 年 9 月更新

自從撰寫這篇文章以來，Notion 現在有了公共 API。然而，我們最終還是選擇了 MDX 作為部落格內容的格式。

我們在使用 Notion 時遇到的問題是，未經批准的外部貢獻者提交的 PR 會導致文件構建失敗。這是因為使用 Notion 作為 CMS 需要一個秘密 API 令牌，而 Vercel 正確地不允許組織外部的開發人員訪問 PR 部署。這並非 Notion 特有的問題，任何用於支援 OSS 專案部落格的 headless CMS 都會遇到相同的問題。這使得在 GitHub 上瀏覽 Formik 的 issue 變得困難，因為每個 PR 都會直接失敗。此外，對於新的貢獻者來說，即使他們沒有做錯任何事，看到一個紅色的 X 也不是一個好的體驗。

此時，我們可以將部落格移至其自己的 repo 或網站，但我們認為放棄 Notion，使用好用的 MDX 並將所有內容保留在程式碼庫中會更容易。

除了 Notion 的公共 API 之外，Docusaurus v2 也更新並改進了其行動裝置導覽功能。它值得一試，還有另一個名為 Nextra 的專案，它類似於 Docusaurus，但由 Next.js 支援。如果我今天要重寫 Formik 文件，我可能會 fork nextra-theme-docs。