协议：您下一个 API 文档站点的美丽起点

经过数月的努力，我很高兴终于发布我们的下一个网站模板—— 协议，这是一个美丽的入门套件，用于构建惊人的 API 参考网站。

基于 Next.js 和 MDX，并使用 Tailwind CSS 进行样式设计，它的构建方式正是我们构建自己 API 参考文档的方式。

可以玩一下实时演示，或者如果您拥有 Tailwind UI 的全访问许可证，可以下载源代码——当然，这是对全访问客户的免费更新。

设计细节丰富

像往常一样，我们在设计上乐在其中，并在这些细节上增加了一层额外的打磨，使浏览网站变得更加愉悦。

我们有粘性代码块，在您查看该端点的请求和响应详细信息时保持在视图中：

主页卡片上还有这种美丽的悬停效果——它跟随您的鼠标光标，显示出一种渐变光辉，揭示出微妙的背景图案：

不过，我最喜欢的细节必须是侧边导航，它跟踪可见的页面内容，但使用一种“迷你地图”策略，所有可见的页面部分都被高亮显示：

在您滚动页面时观看这个动画真的是一场视觉盛宴——感谢 Framer Motion 一如既往地完成这项繁重的工作。即使我绝对讨厌 React，我也肯定会使用它，仅仅是为了使用这个库，实在是太棒了。

我们希望的开发者体验

我们花了很多时间决定如何连接这个项目的实际内容。我们探索了多种使用不同标准自动生成文档的选项，但就我个人而言，这一切感觉都有点限制。

我个人希望能够准确写出我想要的文档。因此，对于 Protocol，我们优化了最大控制，但提供了很多写作便利，使您能够快速准确地写出您想要的内容。

您可以用 MDX 编写端点文档，快速混合我们提供的一些小组件来构建结构：

messages.mdx

## 创建一条消息 {{ tag: 'POST', label: '/v1/messages' }}
<Row>
  <Col>
    发布一条新消息到特定对话中。
    ### 必需属性
    <Properties>
      <Property name="conversation_id" type="string">
        消息所属对话的唯一标识符。
      </Property>
      <Property name="message" type="string">
        消息内容。
      </Property>
    </Properties>
  </Col>
  <Col sticky>
    <CodeGroup title="请求" 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="你就是法国人所说的 'les incompetents.'"
    ```
    ```js
    import ApiClient from '@example/protocol-api'
    const client = new ApiClient(token)
    await client.messages.create({
      conversation_id: 'xgQQXg3hrtjh7AvZ',
      message: '你就是法国人所说的 'les incompetents.'',
    })
    ```
    </CodeGroup>
    ```json {{ title: '响应' }}
    {
      "id": "gWqY86BMFRiH5o11",
      "conversation_id": "xgQQXg3hrtjh7AvZ",
      "message": "你就是法国人所说的 'les incompetents.'",
      "reactions": [],
      "created_at": 692233200,
    }
    ```
  </Col>
</Row>

这将生成如下的文档：

为了真正完善编写体验，我们甚至构建了 mdx-annotations——一个新库，将我们在使用 Markdoc 时喜爱的注释功能引入到 MDX。

它让您可以通过使用一个对象对标记进行注释，将 props 传递到 MDX 内容中的标签中，如下标题所示：

## 创建一条消息 { tag: 'POST', label: '/v1/messages' }

...这将被转换为以下 JSX：

<Heading level={2} tag="POST" label="/v1/messages">
  创建一条消息
</Heading>

这使您可以更加快速地进行编写，因为您可以继续使用 Markdown，而不必深入到原始 JSX 中仅仅是为了传递一些额外的数据。

可调适的设计

我认为这个模板将对很多人非常有用，因此对我们来说，能够轻松自定义设计以匹配您品牌的样式非常重要。

我们故意设计了我们在网站中使用的插图背景图案，使其对基本上任何人都感觉“与品牌契合”——您可以看出这是专业设计师的作品，但它简单，并且主题偏向于“技术”，这正是所有 API 参考网站共通的特点。

我们在代码中构建了该图案，而不是将其作为已经包含所有颜色的数据的资产输出，因此很容易调整以匹配您自己的配色方案。

在语法高亮方面，我们使用了 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");
}