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

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

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

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

设计细节丰富

和往常一样，我们在设计方面玩得很开心，并对细节进行了精细打磨，使浏览网站的体验非常愉悦。

我们有粘性代码块，在您查看该端点的请求和响应细节时始终保持可见：

首页卡片上还有美丽的悬停效果——它会随着鼠标光标移动而产生渐变光晕，揭示出细腻的背景图案：

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

在您滚动页面时观看这个动画，真是令人惊叹——感谢 Framer Motion 一如既往地处理了繁重的工作。即使我绝对讨厌 React，我也肯定会使用它，只是为了使用这个库，真的太棒了。

我们想要的开发者体验

我们花了很多时间来决定如何连接这个项目的实际内容。我们探索了许多不同的选项，以使用不同的标准自动生成文档，但对于我的口味来说，这一切都感觉有些限制。

我个人希望能够完全按照自己的意愿编写文档。因此，对于协议，我们优化了控制能力，同时提供了很多编写便利，使得快速精准地编写所需内容成为可能。

您在 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");}