MkDocs vs Read the Docs: What are the differences?

1. Storage and Hosting: The key difference between MkDocs and Read the Docs lies in the storage and hosting approach. MkDocs generates static HTML files, meaning the documentation is stored and hosted on a server or web hosting platform as simple HTML pages. On the other hand, Read the Docs dynamically generates documentation in real-time, querying the code repository and dynamically serving the documentation pages.
2. Configuration and Customization: MkDocs provides a more straightforward and simplistic configuration system, with a single configuration file (usually named mkdocs.yml) where users can define basic settings and options. Read the Docs, on the other hand, offers more extensive customization options through its comprehensive configuration system, allowing fine-grained control over themes, translations, and versioning.
3. Build Process: MkDocs has a simple build process, where running the build command (e.g., mkdocs build) generates the entire documentation site in the output directory. This process is relatively fast, making it easy to update and publish changes. Read the Docs, however, has a more complex build process, involving a multitude of steps such as fetching the code, building the documentation, managing versions, and configuring the server. This can slow down the overall build and deployment process.
4. Search Functionality: MkDocs relies on third-party search plugins or tools for implementing search functionality in the documentation site. Users can choose from a range of available plugins or tools that integrate with MkDocs. Read the Docs, on the other hand, includes a built-in search functionality that is automatically enabled for all projects. This eliminates the need for additional setup or configuration for search capabilities.
5. Support for Multiple Versions: MkDocs does not have built-in support for managing multiple versions of documentation. Each version of the documentation needs to be manually managed and maintained separately. Read the Docs, however, offers robust versioning support, allowing easy management of multiple versions of the documentation site. It enables users to switch between different versions, view specific historical releases, and compare changes between versions.
6. Hosting Options: MkDocs allows users to choose and set up their preferred hosting platform or server for their documentation site. It provides flexibility in hosting options, allowing users to select a hosting solution that aligns with their specific requirements. In contrast, Read the Docs hosts the documentation directly on its platform, eliminating the need for users to set up their hosting infrastructure. This simplifies the hosting process, particularly for users who prefer an all-in-one solution.

In Summary, MkDocs and Read the Docs differ in their storage and hosting approach, configuration and customization options, build process complexity, search functionality, support for multiple versions, and hosting options.