readme-renderer

Warnings

• breaking The library was originally named `readme` and was renamed to `readme_renderer` to resolve naming conflicts with system files. Users migrating from the old `readme` package must update their imports and dependencies.
  Fix: Update `pip install` commands and Python import statements from `readme` to `readme_renderer`.
• breaking The `cmarkgfm` dependency, essential for Markdown rendering, was moved into an optional extra. If you use `readme-renderer` to process Markdown and do not install it with `[md]` extra, rendering may fail or emit a `UserWarning`.
  Fix: Install the library with the Markdown extra: `pip install readme-renderer[md]`.
• breaking Support for Python 3.7 was dropped. Users on older Python versions will need to upgrade their Python interpreter or use an older `readme-renderer` version.
  Fix: Upgrade Python to 3.8 or newer. The current version (44.0) requires Python >=3.9.
• gotcha reStructuredText content must adhere strictly to the Docutils specification without Sphinx extensions (e.g., directives and roles like `:py:func:`). Invalid markup or Sphinx-specific syntax will cause PyPI to display the raw source instead of a rendered version.
  Fix: Validate reStructuredText carefully, for example, by using `twine check dist/*` on your built distributions, and avoid Sphinx-specific extensions.
• gotcha The library performs HTML sanitization on the rendered output to prevent XSS attacks. This means only a whitelist of HTML tags and attributes are permitted. Custom or unrecognized HTML within your README may be stripped out.
  Fix: Review the allowed HTML tags if embedding HTML directly in your README. Generally, rely on Markdown or reStructuredText syntax for formatting rather than raw HTML.

Install

• pip install readme-renderer Base Installation
• pip install readme-renderer[md] With Markdown Support (recommended for Markdown content)

Imports

• render

  from readme_renderer.markdown import render as render_markdown

• render

  from readme_renderer.rst import render as render_rst

Quickstart

This quickstart demonstrates how to render both Markdown and reStructuredText content into HTML using the `readme_renderer` library. It imports the specific rendering functions from their respective submodules and then calls them with sample content. The output is a string of HTML. Note that for Markdown rendering, the optional `cmarkgfm` dependency is highly recommended, installed via `pip install readme-renderer[md]`.

from readme_renderer.markdown import render as render_markdown
from readme_renderer.rst import render as render_rst

# Example Markdown content
markdown_content = """
# My Project

This is a *great* project with `python` code.

```python
def hello_world():
    print("Hello, PyPI!")
```
"""

# Example reStructuredText content
rst_content = """
My Project
==========

This is a *great* project with ``python`` code.

.. code-block:: python

    def hello_world():
        print("Hello, PyPI!")
"""

# Render Markdown
html_from_markdown = render_markdown(markdown_content)
print("--- Rendered Markdown ---")
print(html_from_markdown[:200] + '...' if len(html_from_markdown) > 200 else html_from_markdown)

# Render reStructuredText
# Note: ensure 'docutils' is installed for rST rendering.
html_from_rst = render_rst(rst_content)
print("\n--- Rendered reStructuredText ---")
print(html_from_rst[:200] + '...' if len(html_from_rst) > 200 else html_from_rst)