rst2gemtext - 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.7
- 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.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?
Changelog
-
[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
andwarning
nodes) (@flozz)
- Handle admonitons (
-
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)
- Pass the source file name to docutils to allow the
-
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