Protocol: 为你的下一个 API 文档网站打造的精美起点

经过数月的制作,我很高兴终于发布我们的下一个网站模板 — Protocol,一个用于构建令人惊叹的 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="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: '响应' }}    {      "id": "gWqY86BMFRiH5o11",      "conversation_id": "xgQQXg3hrtjh7AvZ",      "message": "You're what the French call 'les incompetents.'",      "reactions": [],      "created_at": 692233200,    }    ```  </Col></Row>

这将生成如下所示的文档:

为了真正实现作者体验,我们甚至构建了mdx-annotations — 一个新库,将我们在使用Markdoc时喜欢的注释功能带到 MDX。

它允许你通过用对象注释标签,将属性传递到 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");}