#syntax-highlighting #markdown-html #github #markdown #html #convert #readme


Render Markdown or reStructuredText with syntax highlighting and image filtering similar to GitHub's

3 unstable releases

0.11.0 Apr 7, 2024
0.7.5 Sep 24, 2022
0.7.4 Sep 3, 2022

#1235 in Text processing

Apache-2.0 OR MIT

1.5K SLoC

Render README files the same way(ish) as GitHub et al.

Readme to HTML conversion for lib.rs. It's mostly internal,


  • Markdown (natively in Rust) and
  • reStructuredText (via rst2html),
  • Supports syntax highlighting using Sublime Text syntax definitions.
  • Has twreaks and hacks for Rust language and Rust crates, so e.g. falls back to Rust syntax if it can't detect the language used.


Install docutils package, so that rst2html command is available (in PATH).

It needs to write a file to system's temp directory for rst2html. If you clear temp while the program is running, rst support may fail.

Making a theme

It generates HTML <span> class names based on scope names from Sublime Syntax files, but:

  • words used in the scopes are abbreviated. See highlight.rs for the list of abbreviations.
  • Only scopes with 2 and 3 levels are added (more specific scopes are truncated to the first 3 words).

Adding more languages

All languages are precompiled from syntaxes/ submodule.

tmLanguage definitions need to be converted first.


~360K SLoC