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 内容中的标签来将 props 传递给标签，例如这个标题

## 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

我们是在代码中构建的图案，而不是将其导出为包含所有颜色的资源，因此可以轻松地对其进行调整以匹配您自己的配色方案。

对于语法高亮，我们使用带有 css-variables 主题的 Shiki，这使得通过仅选择 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");
}