Skip to main content

Converts reStructuredText to Gemtext (Gemini markup format)

Project description

GitHub License Discord Github Actions Black

rst2gemtext aims to convert reStructuredText markup to Gemtext, the markup format used by Gemini. It can be used both as a Python library or as a CLI tool.

This project is currently work in progress.


  • Python >= 3.7

  • docutils

  • pygments


pip install rst2gemtext


Command Line Interface (CLI)


rst2gemtext input.rst output.gmi


usage: rst2gemtext [-h] [--print-xml] input_rst output_gemtext

Converts reStructuredText to Gemtext (Gemini markup format)

positional arguments:
  input_rst       the reStructuredText file to convert
  output_gemtext  the output Gemtext file

  -h, --help      show this help message and exit
  --print-xml     print the reStructuredText DOM as XML for debugging purpose

Inaccurate output? Report bugs to

Python Library

Example: Converting a reStructuredText string to a Gemtext string:

import rst2gemtext
output_gemtext = rst2gemtext.convert("my restructured text string")

Example: Converting a reStructuredText file to a Gemtext file:

import rst2gemtext

with open("input.rst", "r") as input_file:
    input_rst =

output_gemtext = rst2gemtext.convert(input_rst)

with open("output.gmi", "w") as output_file:



If you have any question, you can:


Please open an issue on GitHub with as much information as possible if you found a bug:

  • Your operating system / Linux distribution (and its version)

  • How you installed the software

  • All the logs and message outputted by the software

  • etc.

If the issue is about the outputted Gemtext (wrong markup, unsupported reStructuredText feature,…), please provide:

  • An example reStructuedText document that generates the wrong output or that contains the unsupported syntax

  • The wrong Gemtext output (the one currently generated by rst2gemtext)

  • The expected Gemtext output

Pull requests

Please consider filing a bug before starting to work on a new feature; it will allow us to discuss the best way to do it. It is obviously unnecessary if you just want to fix a typo or small errors in the code.

Please note that your code must follow the coding style defined by the pep8 and pass tests. Black and Flake8 are used on this project to enforce the coding style.

Run the tests

You must install Nox first:

pip3 install nox

Then you can check for lint error:

nox --session lint

and run the tests:

nox --session test

You can use following commands to run the tests only on a certain Python version (the corresponding Python interpreter must be installed on your machine):

nox --session test-3.7
nox --session test-3.8
nox --session test-3.9
nox --session test-3.10
nox --session test-3.11

You can also fix coding style errors automatically with:

nox -s black_fix

Support this project

Want to support this project?


  • [NEXT] (changes on master, but not released yet):

    • Nothing yet ;)

  • v0.3.1:

    • Fixed truncated tables when last row contains bullet lists (@flozz, #1)

  • v0.3.0:

    • Handle admonitons (admonition, attention, caution, danger, error, hint, important, note, tip and warning nodes) (@flozz)

  • v0.2.0:

    • Pass the source file name to docutils to allow the include directive to work (@flozz)

    • Added a basic support of the table (and associatad) nodes (@flozz)

  • v0.1.0:

    • Initial release.

    • Supported rst nodes:

      • block_quote

      • bullet_list

      • caption

      • comment

      • emphasis

      • enumerated_list

      • figure

      • image

      • list_item

      • literal

      • literal_block

      • paragraph

      • raw

      • reference

      • section

      • strong

      • substitution_definition

      • substitution_reference

      • system_message

      • target

      • Text

      • title

      • transition

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rst2gemtext-0.3.1.tar.gz (21.8 kB view hashes)

Uploaded Source

Built Distribution

rst2gemtext-0.3.1-py3-none-any.whl (22.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page