4.2 KiB
| template |
|---|
| overrides/main.html |
Alternatives
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
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
- Large and rich ecosystem, backed by Facebook
Challenges
- High learning curve, JavaScript knowledge mandatory
- JavaScript ecosystem is very volatile, rather high maintenance
- More time necessary needed to get up and running
While Docusaurus is one of the best choices when it comes to documentation sites that output a single page applications, there are many more solutions, including Docz, Gatsby, Vuepress and Docsify that approach this problem similarily.
Jekyll
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.)
- Generates a SEO-friendly site, similar to Material for MkDocs
Challenges
-
Not specifically geared towards technical project documentation
-
Limited Markdown capabilities, not as advanced as Python Markdown
-
More time necessary needed to get up and running
Sphinx
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
- Generates reference documentation from Python Docstrings
- Large and rich ecosystem, used by many Python projects
Challenges
- High learning curve, reStructured text syntax might be challenging
- Search is less powerful than the one provided by MkDocs
- More time necessary needed to get up and running
Sphinx Immaterial is a great port of Material for MkDocs to Sphinx, as it follows the upstream repository closely. Furo is another great theme. Alternatively, mkdocstrings builds on top of MkDocs to allow the generation of reference documentation.
GitBook
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
- Limited Markdown capabilities, not as advanced as Python Markdown
- Many Open Source projects moved away from GitBook
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.