Tailwind CSS 主页
返回

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

日期

经过几个月的制作，我终于很高兴发布我们的下一个网站模板——协议，一个用于构建出色 API 参考网站的精美入门套件。

Learn about the Protocol template

它由 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');
}

这比从头开始创建自己的主题要轻松得多！

除了我们在演示中使用的四个图标外，我们还包含了另外 24 个图标，用于各种常见的 API 资源类型。

查看此屏幕截图，我们已将 Protocol 模板改编为 ConvertKit 朋友使用它来为其 API 参考提供支持。

乍一看，看起来大不相同，但当你真正深入研究时，实际上并没有改变多少——只是更新了一些按钮和链接颜色、徽标、调整插图中的渐变，以及选择一些不同的语法高亮显示颜色。

暗黑模式

当然，该网站包括暗黑模式支持——它专为开发人员设计，你真的认为我们会如此无知吗？你永远不会原谅我们。

The Protocol template design in dark mode

暗黑模式版本也有很多自己的酷炫设计细节——例如，我喜欢不同的主要按钮处理。

带有 Algolia DocSearch 集成的命令面板

我们喜欢 Algolia 用于文档搜索，我们也将其用于 Tailwind CSS 网站以及我们的 Syntax 模板。

我们也为 Protocol 连接了它，但这次使用 Algolia 的无头 自动完成库，因此我们可以完全控制搜索 UI。

这种方法的好处是，我们可以使用普通的实用程序类来为所有内容设置样式，而不是编写自定义 CSS 来为已经设置样式的小部件设置样式，这在 Tailwind CSS 项目中感觉更“正确”。

就是这样——2022 年的最后一个 Tailwind UI 模板！我们还有 另一个 即将发布，所以新年记得关注一下。很快也会有一些非常令人兴奋的 Tailwind CSS v4.0 新闻要分享！