Example projects

  • Need inspiration?

  • Want to bootstrap a new documentation project?

  • Want to showcase your own solution?

The following example projects show a rich variety of uses of Read the Docs. You can use them for inspiration, for learning and for recipes to start your own documentation projects. View the rendered version of each project and then head over to the Git source to see how it’s done and reuse the code.

Sphinx and MkDocs examples

Topic

Framework

Links

Description

Basic Sphinx

Sphinx

[Git] [Rendered]

Sphinx example with versioning and Python doc autogeneration

Basic MkDocs

MkDocs

[Git] [Rendered]

Basic example of using MkDocs

Jupyter Book

Jupyter Book and Sphinx

[Git] [Rendered]

Jupyter Book with popular integrations configured

Basic AsciiDoc

Antora

[Git] [Rendered]

Antora with asciidoctor-kroki extension configured for AsciiDoc and Diagram as Code.

Real-life examples

Awesome List badge

We maintain an Awesome List where you can contribute new shiny examples of using Read the Docs. Please refer to the instructions on how to submit new entries on Awesome Read the Docs Projects.

Contributing an example project

We would love to add more examples that showcase features of Read the Docs or great tools or methods to build documentation projects.

We require that an example project:

  • is hosted and maintained by you in its own Git repository, example-<topic>.

  • contains a README.

  • uses a .readthedocs.yaml configuration.

  • is added to the above list by opening a PR targeting examples.rst.

We recommend that your project:

  • has continuous integration and PR builds.

  • is versioned as a real software project, i.e. using git tags.

  • covers your most important scenarios, but references external real-life projects whenever possible.

  • has a minimal tech stack – or whatever you feel comfortable about maintaining.

  • copies from an existing example project as a template to get started.

We’re excited to see what you come up with!