Skip to content

替代方案

¥Alternatives

市面上有大量的静态网站生成器和主题，选择适合您的技术栈的产品是一个艰难的决定。如果您不确定 Material for MkDocs 是否适合您，本节应该可以帮助您评估其他解决方案。

¥There are tons of static site generators and themes out there and choosing the right one for your tech stack is a tough decision. If you're unsure if Material for MkDocs is the right solution for you, this section should help you evaluate alternative solutions.

多库萨乌斯

¥Docusaurus

Facebook 的Docusaurus是一款非常流行的文档生成器，如果您或您的公司已经在使用React构建网站，那么 Docusaurus 是一个不错的选择。它将生成一个单页应用程序，这与 Material for MkDocs 为您生成的网站截然不同。

¥Docusaurus by Facebook is a very popular documentation generator and a good choice if you or your company are already using React to build your site. It will generate a single page application which is fundamentally different from the site Material for MkDocs generates for you.

优势

¥Advantages

  • 非常强大、可定制、可扩展

    ¥Very powerful, customizable and extendable

  • 提供许多有助于技术写作的组件

    ¥Provides many components that aid in technical writing

  • 庞大而丰富的生态系统，由 Facebook 提供支持

    ¥Large and rich ecosystem, backed by Facebook

挑战

¥Challenges

  • 学习难度高，必须具备 JavaScript 知识

    ¥High learning curve, JavaScript knowledge mandatory

  • JavaScript 生态系统非常不稳定，维护成本较高

    ¥JavaScript ecosystem is very volatile, rather high maintenance

  • 需要更多时间才能启动并运行

    ¥More time needed to get up and running

虽然Docusaurus是输出单页应用程序的文档站点的最佳选择之一，但还有许多其他解决方案，包括Docz 、 Gatsby 、 Vuepress和Docsify，它们以类似的方式解决此问题。

¥While Docusaurus is one of the best choices when it comes to documentation sites that output a single page application, there are many more solutions, including Docz, Gatsby, Vuepress and Docsify that approach this problem similarly.

杰基尔

¥Jekyll

Jekyll可能是最成熟、使用最广泛的静态站点生成器之一，它是用Ruby编写的。它并非专门针对技术项目文档，而且有很多主题可供选择，这可能有点困难。

¥Jekyll is probably one of the most mature and widespread static site generators and is written in Ruby. It is not specifically geared towards technical project documentation and has many themes to choose from, which can be challenging.

优势

¥Advantages

  • 久经考验，生态系统丰富，主题众多可供选择

    ¥Battle-tested, rich ecosystem, many themes to choose from

  • 为博客带来强大的功能（永久链接、标签等）

    ¥Brings great capabilities for blogging (permalinks, tags, etc.)

  • 生成 SEO 友好的网站，类似于 Material for MkDocs

    ¥Generates a SEO-friendly site, similar to Material for MkDocs

挑战

¥Challenges

  • 并非专门针对技术项目文档

    ¥Not specifically geared towards technical project documentation

  • Markdown 功能有限，不如 Python Markdown 先进

    ¥Limited Markdown capabilities, not as advanced as Python Markdown

  • 需要更多时间才能启动并运行

    ¥More time needed to get up and running

狮身人面像

¥Sphinx

Sphinx是一款替代的静态站点生成器，专门用于生成参考文档，提供 MkDocs 所缺乏的强大功能。它使用reStructured text （一种类似于 Markdown 的格式），有些用户觉得这种格式比较难用。

¥Sphinx is an alternative static site generator specifically geared towards generating reference documentation, offering powerful capabilities that are lacking in MkDocs. It uses reStructured text, a format similar to Markdown, which some users find harder to use.

优势

¥Advantages

  • 非常强大、可定制、可扩展

    ¥Very powerful, customizable and extendable

  • 从Python 文档字符串生成参考文档

    ¥Generates reference documentation from Python docstrings

  • 庞大而丰富的生态系统，被许多 Python 项目使用

    ¥Large and rich ecosystem, used by many Python projects

挑战

¥Challenges

  • 学习曲线高，重构文本语法可能具有挑战性

    ¥High learning curve, reStructured text syntax might be challenging

  • 搜索功能不如 MkDocs 提供的强大

    ¥Search is less powerful than the one provided by MkDocs

  • 需要更多时间才能启动并运行

    ¥More time needed to get up and running

如果您正在考虑使用 Sphinx，因为您需要生成参考文档，那么您应该尝试一下mkdocstrings - 一个在 MkDocs 之上构建的积极维护和流行的框架，实现类似 Sphinx 的功能。

¥If you're considering using Sphinx because you need to generate reference documentation, you should give mkdocstrings a try – an actively maintained and popular framework building on top of MkDocs, implementing Sphinx-like functionality.

GitBook

¥GitBook

GitBook提供了一个托管文档解决方案，可以将 GitHub 仓库中的 Markdown 文件生成美观实用的网站。它曾经是开源的，但不久前变成了闭源解决方案。

¥GitBook offers a hosted documentation solution that generates a beautiful and functional site from Markdown files in your GitHub repository. However, it was once Open Source, but turned into a closed source solution some time ago.

优势

¥Advantages

  • 托管解决方案，只需极少的技术知识

    ¥Hosted solution, minimal technical knowledge required

  • 自定义域、身份验证和其他企业功能

    ¥Custom domains, authentication and other enterprise features

  • 为团队提供出色的协作功能

    ¥Great collaboration features for teams

挑战

¥Challenges

  • 闭源，专有项目不免费

    ¥Closed source, not free for proprietary projects

  • Markdown 功能有限，不如 Python Markdown 先进

    ¥Limited Markdown capabilities, not as advanced as Python Markdown

  • 许多开源项目都已不再使用 GitBook

    ¥Many Open Source projects moved away from GitBook

许多用户从GitBook转向 Material for MkDocs，因为他们希望保留对文档的控制权和所有权，并倾向于开源解决方案。

¥Many users switched from GitBook to Material for MkDocs, as they want to keep control and ownership of their documentation, favoring an Open Source solution.