Recommendations - Furo

Furo is under active development, and this documentation is not written yet!

# Recommendations

This page lists a few opinionated recommendations for Sphinx plugins to use in your documentation along with Furo. All these plugins work well with Furo-based Sphinx documentation, but they are not inherently tied to Furo.

MyST (Markedly Structured Text)

  This project enables writing documentation with Markdown in Sphinx1. This is achieved by making well-thought-out extensions to the CommonMark Specification, which make it as capable as reStructuredText. In case you’re wondering if that works well… Furo’s documentation is written using MyST.

  Markdown is a significantly more popular markup format than reStructuredText. This means that it’s likely that potential contributors/developers on the project are significantly more familiar with Markdown than reStructuredText. MyST gives you the best of both worlds – simplicity and familiarity of Markdown with the extensibility power of reST.

sphinx-inline-tabs

  This project provides a straightforward way to introduce tabbed content within your documentation. This is useful for instructions specific to something about the end user (like their OS, or preferred language, etc). This is a great way to organise complex bits of documentation without major trouble.

  Disclaimer: I am the creator and the primary maintainer of sphinx-inline-tabs.

sphinx-autobuild

  This project provides a live-reloading server, that rebuilds the documentation and refreshes any open pages automatically when changes are saved. This enables a much shorter feedback loop which can help boost productivity when writing documentation. Furo’s development workflow is based on uses this project.

  Disclaimer: I am the primary maintainer of sphinx-autobuild.

sphinx-copybutton

  This project adds a convenient copy button to code blocks. This is a subtle but effective user experience improvement when there are code snippets that a user might wish to copy from (examples, sample code etc).

In addition to the above, a shoutout to the Executable Books project which maintains many useful Sphinx extensions including some listed above.

1

  MyST addresses all the concerns that have been raised when arguing against Using Markdown for Technical Documentation, which really only leaves us with the good bits. :)