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.