Code Formatting for the ReadTheDocs System

Code Formatting for the ReadTheDocs System

August 6, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Code Formatting for the ReadTheDocs System

Improving Code Formatting on ReadTheDocs

As a developer documenting your command line system using ReadTheDocs, you might face challenges with formatting shell output correctly. The platform, by default, attempts to apply source code highlighting to any text it interprets as code blocks.

Identifying the Issue

When you include raw shell commands or output in your documentation, ReadTheDocs may misinterpret certain keywords and syntax elements:

$ magento2:generate

In this example, ReadTheDocs is treating magento2:generate as though it were a class constant within source code, which leads to unusual formatting.

Controlling Code Formatting with Sphinx or Mkdocs

Since ReadTheDocs transforms your Markdown or Sphinx files into HTML, the control over code block formatting lies at the markup level. Here are some steps to ensure proper rendering:

Using Sphinx: Disable Source Code Highlighting

If you’re using Sphinx for documentation, you can disable source code highlighting entirely in your conf.py file:

highlight_language = 'none'

This global setting will stop ReadTheDocs from attempting to apply syntax coloring to any text within your Markdown.

Using Mkdocs: Use Code Blocks with No Language

In Mkdocs, you can use the standard Markdown code block but specify language: none to prevent syntax highlighting:

$ magento2:generate

Customizing Formatting at a Granular Level

For more granular control, you can explicitly mark specific lines as regular text or apply custom formatting:

Using Backticks for Regular Text

Wrapping keywords in backticks (`) to prevent syntax highlighting:

$ `magento2:generate`

Using ReStructuredText for Sphinx Users

Sphinx users can use the :: directive followed by a line of regular text:

.. code-block:: none

    $ magento2:generate

Conclusion

Controlling source code formatting in ReadTheDocs requires adjusting your markup at the Sphinx or Mkdocs level. By disabling syntax highlighting globally or marking specific lines as regular text, you can ensure that crucial shell commands and output are displayed accurately.

Remember to test your documentation thoroughly after each change to ensure the desired formatting is applied consistently across all pages.

For more advanced customizations and best practices in technical writing, consider exploring Laravel Company’s resources on efficient code documentation strategies.

Magento 2 Configuration Pricing Errors

Our network