Creates a simple mobile-friendly static website from your README.

Beautiful-readme converts a single readme file into a simple and modern Bootstrap-powered static website. Simplicity (KISS) and clarity are the major design goals of beautiful-readme. For more feature-rich solutions, I recommend having a look at Sphinx and Beautiful docs.


Here (built from this readme) and here (built from a readme for another project).

Usage example


  • A small configuration file (default name:
  • A readme file (reStructuredText or Markdown), e.g. README.rst.

Execute $ beautiful-readme README.rst and a static website is created in the _build directory.


  • reStructuredText and Markdown support.
  • Modern and reliable HTML5 output (based on the Bootstrap blog template).
  • Mobile-friendly responsive layout with professional appearance.
  • Google Analytics snippet support (optional).
  • Custom CSS injection (optional).
  • Custom sidebar HTML code injection (optional).


Beautiful-readme releases are hosted on PyPI. Installation with pip is recommended:

$ pip install beautiful-readme

Author & License

Beautiful-readme is written and maintained by Jan-Philip Gehrcke. It is licensed under an MIT license (see LICENSE file).


Version 0.1.0 (Month dd, YYYY)

  • Initial release.