Protocol：您下一個 API 文件網站的美好起點

經過幾個月的製作，我很高興終於發布我們的下一個網站範本 — Protocol，一個用於構建令人驚嘆的 API 參考網站的美麗入門套件。

它由 Next.js 和 MDX 提供支持，並使用 Tailwind CSS 設計樣式，完全按照我們構建自己的 API 參考文件的做法來構建。

如果您擁有 Tailwind UI 全面訪問許可證，可以試玩線上演示或下載原始碼 — 當然，這對所有全面訪問客戶來說都是免費更新。

充滿設計細節

像往常一樣，我們在設計上玩得很開心，並且在事物上添加了額外的潤飾層，使其在瀏覽網站時真正令人愉快。

我們有粘性的程式碼區塊，當您捲動瀏覽該端點的請求和響應詳細資訊時，這些程式碼區塊會保持在視圖中。

首頁卡片上也有這種美麗的懸停效果 — 它會跟隨您的滑鼠游標，並以漸層發光來揭示微妙的背景圖案。

我最喜歡的細節還是側邊欄導覽，它會追蹤可見的頁面內容，但使用一種「迷你地圖」策略，其中會突出顯示所有可見的頁面區段。

看著它在您捲動頁面時進行動畫，真是令人賞心悅目 — 感謝 Framer Motion 像往常一樣在這裡進行繁重的工作。即使我非常討厭 React，我仍然很確定我會使用它只是為了使用這個庫，它真的太棒了。

我們自己想要的開發人員體驗

我們花了很多時間來決定如何在此處連接實際內容。我們探索了許多不同的選項，以使用不同的標準自動產生文件，但無論如何就我的口味而言，感覺都有點受限制。

就我個人而言，我希望能夠直接編寫我想要的文件。因此，對於 Protocol，我們針對最大控制進行了優化，同時提供了許多編寫便利，使您可以真正輕鬆地快速編寫您想要的內容。

您可以使用 MDX 編寫端點文件，混合使用我們提供的一些小組件來快速構建內容。

messages.mdx

## Create a message {{ tag: 'POST', label: '/v1/messages' }}<Row>  <Col>    Publishes a new message to a specific conversation.    ### Required attributes    <Properties>      <Property name="conversation_id" type="string">        Unique identifier for the conversation the message belongs to.      </Property>      <Property name="message" type="string">        The message content.      </Property>    </Properties>  </Col>  <Col sticky>    <CodeGroup title="Request" tag="POST" label="/v1/messages">    ```bash {{ title: 'cURL' }}    curl https://api.protocol.chat/v1/messages \      -H "Authorization: Bearer {token}" \      -d conversation_id="xgQQXg3hrtjh7AvZ" \      -d message="You're what the French call 'les incompetents.'"    ```    ```js    import ApiClient from '@example/protocol-api'    const client = new ApiClient(token)    await client.messages.create({      conversation_id: 'xgQQXg3hrtjh7AvZ',      message: 'You're what the French call 'les incompetents.'',    })    ```    </CodeGroup>    ```json {{ title: 'Response' }}    {      "id": "gWqY86BMFRiH5o11",      "conversation_id": "xgQQXg3hrtjh7AvZ",      "message": "You're what the French call 'les incompetents.'",      "reactions": [],      "created_at": 692233200,    }    ```  </Col></Row>

這將產生如下所示的文件

Example of generated documentation from MDX source

為了真正實現編寫體驗，我們甚至建立了 mdx-annotations — 一個新的函式庫，將我們在使用 Markdoc 時喜歡的註解功能引入 MDX。

它讓您可以通過使用物件註解它們，將屬性傳遞到 MDX 內容中的標籤，例如這個標題

## Create a message { tag: 'POST', label: '/v1/messages' }

...它會轉換為這個 JSX

<Heading level={2} tag="POST" label="/v1/messages">  Create a message</Heading>

這讓您可以更快地移動，因為您可以繼續使用 Markdown 編寫，而不必為了傳遞一些額外的資料而掉入原始 JSX 中。

適應性設計

我認為這個範本對於許多人來說會非常有用，因此對我們來說，重要的是它很容易自訂設計以符合您的品牌。

我們刻意設計了在網站中使用的插圖背景圖案，讓基本上任何人都會覺得「符合品牌形象」 — 您可以看出來它出自專業設計師之手，但它很簡單，並傾向於「技術」主題，這也是所有 API 參考網站都會有的共同之處。

The illustrated background pattern included in this template

我們在程式碼中構建了該圖案，而不是將其匯出為帶有所有內建色彩的資產，因此可以很容易地調整它以符合您自己的配色方案。

對於語法突出顯示，我們使用 Shiki 和 css-variables 主題，只需選擇 9 種顏色，即可輕鬆更新您品牌的語法突出顯示

:root {  --shiki-color-text: theme("colors.white");  --shiki-token-constant: theme("colors.emerald.300");  --shiki-token-string: theme("colors.emerald.300");  --shiki-token-comment: theme("colors.zinc.500");  --shiki-token-keyword: theme("colors.sky.300");  --shiki-token-parameter: theme("colors.pink.300");  --shiki-token-function: theme("colors.violet.300");  --shiki-token-string-expression: theme("colors.emerald.300");  --shiki-token-punctuation: theme("colors.zinc.200");}