rst2gemtext 0.5.0

Converts reStructuredText to Gemtext (Gemini markup format)

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.

Requirements

• Python >= 3.9

• docutils

• pygments

Installation

pip install rst2gemtext

Usage

Command Line Interface (CLI)

Example:

rst2gemtext input.rst output.gmi

Usage:

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

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

Inaccurate output? Report bugs to https://github.com/flozz/rst2gemtext/issues

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 = input_file.read()

output_gemtext = rst2gemtext.convert(input_rst)

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

Contributing

Questions

If you have any question, you can:

• Open an issue on GitHub

• Ask on Discord (I am not always available to chat, but I try to answer to everyone)

Bugs

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.9
nox --session test-3.10
nox --session test-3.11
nox --session test-3.12
nox --session test-3.13

You can also fix coding style errors automatically with:

nox -s black_fix

Support this project

Want to support this project?

• ☕️ Buy me a coffee

• 💵️ Give me a tip on PayPal

• ❤️ Sponsor me on GitHub

Changelog

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

  • Nothing yet ;)

• v0.5.0:

  • feat(attribution_node): Added support for attribution nodes used by the epigraph directive (#8, @flozz)

  • fix: Fixed ImportError with docutils >= 0.22 (#7, @flozz)

  • Fix(image_node): Merge image link and its target link if both are identical (#6, @flozz)

  • misc(packaging): Modernized packaging: replaced setup.py and setuptools by pyproject.toml and flit (@flozz)

• v0.4.0:

  • feat: Skip topic nodes as the ToC will not be generated (@flozz)

  • fix: Fixed bad link list deduplication when a non-breaking space is used in anchor text (@flozz)

  • fix: Fixed troncated tables when multiline content is present in the last row (@flozz)

  • misc(deps): Added Python 3.12, 3.13 support (@flozz)

  • misc(deps)!: Removed Python 3.7, 3.8 support (@flozz)

• v0.3.1:

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

• v0.3.0:

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

• v0.2.0:

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

  • feat: Added a basic support of the table (and associated) 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