H

How I build a Documentation site using Docz Introduction Setting up the environment Setting up the Docz Creating the first page Project Configuration Running the server Conclusion

2025-06-08

如何使用 Docz 构建文档网站

介绍

设置环境

设置 Docz

创建第一个页面

项目配置

运行服务器

结论

介绍

我使用任何开发工具或库时都会参考其文档。我会参考文档来了解这些工具以及如何将它们集成到不同的设置中。如果文档不够完善，我就会放弃这个工具，因为我需要花更长的时间才能通过其他文章和视频弄清楚它的工作原理。

文档是工具知识的原始来源，之后会扩展为特定主题的文章和视频。因此，拥有结构良好、格式规范的文档至关重要。同时，从头开始构建文档可能耗时很长。因此，使用工具/框架来创建文档是首选。Docz 就是这样一款创建文档网站的工具。

我使用 Docz 为我的awesome-web3.0 （学习 Web 3.0 的优秀资源集合）GitHub 仓库创建了一个文档网站。您可以在这里访问该网站。

awesome-web3

它外观精美，支持明暗主题。使用 Docz 构建美观的网站非常简单。文档采用 Markdown 编写，这是大多数开发人员的首选文本编写方式。

希望以上内容能让您兴奋不已，因为我们即将构建一个包含所有这些功能的网站。让我们开始吧。

设置环境

在开始构建之前，我们需要预先安装以下内容：

  • NodeJS：它是一个 JavaScript 运行时，允许 JavaScript 在终端中运行。它将附带npm，允许运行命令来安装必要的库。
  • Gatsby CLI：由于 Docz 是基于 Gatsby 开发的，因此我们需要安装 Gatsby CLI。安装方法如下：安装 NodeJS 后，运行以下命令。
    npm install -g gatsby-cli
Enter fullscreen mode Exit fullscreen mode

他们很快就会将其改为Astro。

这就是我们现在所需要的，让我们设置 Docz。

设置 Docz

导航到要创建项目的目录。首先，打开终端并运行以下命令来创建一个package.json文件，用于管理我们的依赖项和脚本。

    npm init -y
Enter fullscreen mode Exit fullscreen mode

现在，是时候安装我们项目的依赖项了。让我们来看看它们。

  • docz：它是将 docz 功能添加到我们的应用程序的库。
  • react 和 react-dom：由于 docz 基于 React 框架 Gatsby，所以我们需要安装 react。

您可以使用以下命令安装上述所有依赖项：

    npm install docz react react-dom
Enter fullscreen mode Exit fullscreen mode

现在，我们需要在文件中添加一些package.json用于运行和构建应用程序的脚本。具体如下。

      "scripts": {
        "dev": "docz dev",
        "build": "docz build",
        "serve": "docz build && docz serve"
      },
Enter fullscreen mode Exit fullscreen mode

创建第一个页面

为了显示页面，Docz 需要一个.mdx文件。它是 Markdown 的一个扩展，允许在 Markdown 中使用 JSX 以及其他一些很酷的功能。您可以在这里了解更多信息。您可以在根目录中添加一个 Markdown 文件，但我建议将所有文件添加到src/根目录中。您可以使用扩展名随意命名文件.mdx。

在每个文件的顶部，我们需要定义一些属性。我们来讨论一下其中的一些。

  • name：这是一个必需属性，其值是页面的名称。
  • route：您可以在此处定义页面渲染到的路由。如果未定义，则将使用文件路径作为路由。
  • 菜单：您可以创建任何主页面的子页面。例如，在“安装”中，我们可以提供适用于 Windows、macOS 和 Linux 的安装指南。

所有这些属性都定义在两个三重连字符 (---) 内。您可以在下面查看。

    ---
    name: Web3
    route: /web3
    menu: Web2 Vs Web3
    ---
Enter fullscreen mode Exit fullscreen mode

在结束的三连字符下方，您可以添加 Markdown 格式的页面内容。我们也来添加一些吧。

    # Blockchain

    > Blockchain is a non-modifiable ledger system that records the transaction and it is shared across the node i.e, the computer participating in the network.

    ![Blockchain Development\](https://img.freepik.com/free-vector/security-concept-illustration-people-holding-chain_53876-43028.jpg?t=st=1652793493~exp=1652794093~hmac=56d57921d4f37f94370ef406fb5327b90da8af413bf90286bf2553de7feeae1c&w=740)
Enter fullscreen mode Exit fullscreen mode

项目配置

您可以为项目配置各种功能。您可以点击此处了解详情。我们将在项目中添加一些功能。首先，我们需要doczrc.js在根目录中创建一个同名文件。在这里，我们将添加配置的属性。让我们来详细了解一下。

  • 标题：这是我们页面的标题，将显示在文档页面的顶部。
  • 描述：顾名思义，就是文档的描述。
  • 菜单：这个很有意思，你可以按照你想要的显示顺序排列页面。它是我们在每个文档中添加的文档名称的数组。

这将使我们的doczrc.js文件看起来像这样：

    export default {
        title:'Awesome Web3.0',
        menu: [
          'Web3',
          'Web3 Roadmap with free resources',
          'Web2 VS Web3',
          'Blockchain',
          'Ethereum',
          'Decentralized Application(dApp)',
          'Smart Contract',
          'Solidity',
          'Remix IDE',
          'Crypto Wallet',
          'Interaction with Blockchain',
          'Local blockchain development environment',
          'Framework'
        ],
        description:"Web3 Roadmap and free Resources to learn and ace",
      }
Enter fullscreen mode Exit fullscreen mode

注意：菜单中的文件名来自我的文档网站。

运行服务器

在本地主机上运行服务器非常简单。您可以运行以下命令。

    npm run dev
Enter fullscreen mode Exit fullscreen mode

文档网页

您可以通过右上角的按钮更改主题。默认情况下，它将根据您的浏览器默认设置进行更改。

结论

正如我们所见，使用 Docz 构建文档网站非常容易。您无需构建前端，而且 Docz 可以自定义，打造您自己的专属页面。使用文档构建框架可以节省时间和金钱。

Docz 有一个叫做Playground的功能。它允许你在可编辑的代码编辑器中渲染组件。该组件还会提供实时输出以查看更改。这对于基于组件的库文档非常有用。你可以进一步探索它。

希望本文能帮助您了解 Docz 及其构建文档站点的功能。感谢您阅读这篇博文。

鏂囩珷鏉ユ簮锛�https://dev.to/documatic/how-i-build-a-documentation-site-using-docz-57kk
Devto 翻译
PREV
利用这些技巧和最佳实践来提高代码质量
NEXT
数据加密：使用加密技术保护静态和传输中的数据