rst2gemtext - Converts reStructuredText to Gemtext (Gemini markup format)
=========================================================================
|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.**
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:
.. code-block:: python
import rst2gemtext
output_gemtext = rst2gemtext.convert("my restructured text string")
Example: Converting a reStructuredText file to a Gemtext file:
.. code-block:: python
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 <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub
* `Ask on Discord <https://discord.gg/P77sWhuSs4>`_ (I am not always available to chat, but I try to answer to everyone)
Bugs
~~~~
Please `open an issue <https://github.com/flozz/rst2gemtext/issues>`_ 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 <https://github.com/flozz/rst2gemtext/issues>`_ 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 <https://pep8.org>`_ and pass tests. `Black <https://black.readthedocs.io/en/stable>`_ and `Flake8 <https://flake8.pycqa.org/en/latest>`_ are used on this project to enforce the coding style.
Run the tests
~~~~~~~~~~~~~
You must install `Nox <https://nox.thea.codes/>`__ 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 <https://www.buymeacoffee.com/flozz>`__
* `💵️ Give me a tip on PayPal <https://www.paypal.me/0xflozz>`__
* `❤️ Sponsor me on GitHub <https://github.com/sponsors/flozz>`__
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
.. |GitHub| image:: https://img.shields.io/github/stars/flozz/rst2gemtext?label=GitHub&logo=github
:target: https://github.com/flozz/rst2gemtext
.. |License| image:: https://img.shields.io/github/license/flozz/rst2gemtext
:target: https://github.com/flozz/rst2gemtext/blob/master/COPYING
.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff
:target: https://discord.gg/P77sWhuSs4
.. |Github Actions| image:: https://github.com/flozz/rst2gemtext/actions/workflows/python-ci.yml/badge.svg
:target: https://github.com/flozz/rst2gemtext/actions
.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://black.readthedocs.io/en/stable
Raw data
{
"_id": null,
"home_page": null,
"name": "rst2gemtext",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "restructuredtext, rst, convert, gemtext, gmi, gemini, docutils",
"author": "Fabien LOISON",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/8c/75/15fbef111e5689121f7bd129c2468a3044d4270726f69b8aa1c10ddd1d70/rst2gemtext-0.5.0.tar.gz",
"platform": null,
"description": "rst2gemtext - Converts reStructuredText to Gemtext (Gemini markup format)\n=========================================================================\n\n|GitHub| |License| |Discord| |Github Actions| |Black|\n\nrst2gemtext 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**.\n\n**This project is currently work in progress.**\n\n\nRequirements\n------------\n\n* Python >= 3.9\n* docutils\n* pygments\n\n\nInstallation\n------------\n\n::\n\n pip install rst2gemtext\n\n\nUsage\n-----\n\nCommand Line Interface (CLI)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nExample::\n\n rst2gemtext input.rst output.gmi\n\nUsage::\n\n usage: rst2gemtext [-h] [--print-xml] input_rst output_gemtext\n\n Converts reStructuredText to Gemtext (Gemini markup format)\n\n positional arguments:\n input_rst the reStructuredText file to convert\n output_gemtext the output Gemtext file\n\n options:\n -h, --help show this help message and exit\n --print-xml print the reStructuredText DOM as XML for debugging purpose\n\n Inaccurate output? Report bugs to https://github.com/flozz/rst2gemtext/issues\n\n\nPython Library\n~~~~~~~~~~~~~~\n\nExample: Converting a reStructuredText string to a Gemtext string:\n\n.. code-block:: python\n\n import rst2gemtext\n output_gemtext = rst2gemtext.convert(\"my restructured text string\")\n\nExample: Converting a reStructuredText file to a Gemtext file:\n\n.. code-block:: python\n\n import rst2gemtext\n\n with open(\"input.rst\", \"r\") as input_file:\n input_rst = input_file.read()\n\n output_gemtext = rst2gemtext.convert(input_rst)\n\n with open(\"output.gmi\", \"w\") as output_file:\n output_file.write(output_gemtext)\n\n\nContributing\n------------\n\nQuestions\n~~~~~~~~~\n\nIf you have any question, you can:\n\n* `Open an issue <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub\n* `Ask on Discord <https://discord.gg/P77sWhuSs4>`_ (I am not always available to chat, but I try to answer to everyone)\n\n\nBugs\n~~~~\n\nPlease `open an issue <https://github.com/flozz/rst2gemtext/issues>`_ on GitHub with as much information as possible if you found a bug:\n\n* Your operating system\u00a0/ Linux distribution (and its version)\n* How you installed the software\n* All the logs and message outputted by the software\n* etc.\n\nIf the issue is about the outputted Gemtext (wrong markup, unsupported reStructuredText feature,...), please provide:\n\n* An example reStructuedText document that generates the wrong output or that contains the unsupported syntax\n* The wrong Gemtext output (the one currently generated by rst2gemtext)\n* The expected Gemtext output\n\n\nPull requests\n~~~~~~~~~~~~~\n\nPlease consider `filing a bug <https://github.com/flozz/rst2gemtext/issues>`_ 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.\n\nPlease note that your code must follow the coding style defined by the `pep8 <https://pep8.org>`_ and pass tests. `Black <https://black.readthedocs.io/en/stable>`_ and `Flake8 <https://flake8.pycqa.org/en/latest>`_ are used on this project to enforce the coding style.\n\n\nRun the tests\n~~~~~~~~~~~~~\n\nYou must install `Nox <https://nox.thea.codes/>`__ first::\n\n pip3 install nox\n\nThen you can check for lint error::\n\n nox --session lint\n\nand run the tests::\n\n nox --session test\n\nYou can use following commands to run the tests only on a certain Python version (the corresponding Python interpreter must be installed on your machine)::\n\n nox --session test-3.9\n nox --session test-3.10\n nox --session test-3.11\n nox --session test-3.12\n nox --session test-3.13\n\nYou can also fix coding style errors automatically with::\n\n nox -s black_fix\n\n\nSupport this project\n--------------------\n\nWant to support this project?\n\n* `\u2615\ufe0f Buy me a coffee <https://www.buymeacoffee.com/flozz>`__\n* `\ud83d\udcb5\ufe0f Give me a tip on PayPal <https://www.paypal.me/0xflozz>`__\n* `\u2764\ufe0f Sponsor me on GitHub <https://github.com/sponsors/flozz>`__\n\n\nChangelog\n---------\n\n* **[NEXT]** (changes on ``master``, but not released yet):\n\n * Nothing yet ;)\n\n* **v0.5.0:**\n\n * feat(attribution_node): Added support for ``attribution`` nodes used by the ``epigraph`` directive (#8, @flozz)\n * fix: Fixed ImportError with docutils >= 0.22 (#7, @flozz)\n * Fix(image_node): Merge image link and its target link if both are identical (#6, @flozz)\n * misc(packaging): Modernized packaging: replaced ``setup.py`` and ``setuptools`` by ``pyproject.toml`` and ``flit`` (@flozz)\n\n* **v0.4.0:**\n\n * feat: Skip topic nodes as the ToC will not be generated (@flozz)\n * fix: Fixed bad link list deduplication when a non-breaking space is used in anchor text (@flozz)\n * fix: Fixed troncated tables when multiline content is present in the last row (@flozz)\n * misc(deps): Added Python 3.12, 3.13 support (@flozz)\n * misc(deps)!: Removed Python 3.7, 3.8 support (@flozz)\n\n* **v0.3.1:**\n\n * fix: Fixed truncated tables when last row contains bullet lists (@flozz, #1)\n\n* **v0.3.0:**\n\n * feat: Handle admonitons (``admonition``, ``attention``, ``caution``,\n ``danger``, ``error``, ``hint``, ``important``, ``note``, ``tip`` and\n ``warning`` nodes) (@flozz)\n\n* **v0.2.0:**\n\n * feat: Pass the source file name to docutils to allow the ``include``\n directive to work (@flozz)\n * feat: Added a basic support of the ``table`` (and associated) nodes\n (@flozz)\n\n* **v0.1.0:**\n\n * Initial release.\n * Supported rst nodes:\n\n * block_quote\n * bullet_list\n * caption\n * comment\n * emphasis\n * enumerated_list\n * figure\n * image\n * list_item\n * literal\n * literal_block\n * paragraph\n * raw\n * reference\n * section\n * strong\n * substitution_definition\n * substitution_reference\n * system_message\n * target\n * Text\n * title\n * transition\n\n\n.. |GitHub| image:: https://img.shields.io/github/stars/flozz/rst2gemtext?label=GitHub&logo=github\n :target: https://github.com/flozz/rst2gemtext\n\n.. |License| image:: https://img.shields.io/github/license/flozz/rst2gemtext\n :target: https://github.com/flozz/rst2gemtext/blob/master/COPYING\n\n.. |Discord| image:: https://img.shields.io/badge/chat-Discord-8c9eff?logo=discord&logoColor=ffffff\n :target: https://discord.gg/P77sWhuSs4\n\n.. |Github Actions| image:: https://github.com/flozz/rst2gemtext/actions/workflows/python-ci.yml/badge.svg\n :target: https://github.com/flozz/rst2gemtext/actions\n\n.. |Black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://black.readthedocs.io/en/stable\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Converts reStructuredText to Gemtext (Gemini markup format)",
"version": "0.5.0",
"project_urls": {
"Chat": "https://discord.gg/P77sWhuSs4",
"changelog": "https://github.com/flozz/rst2gemtext?tab=readme-ov-file#changelog",
"documentation": "https://github.com/flozz/rst2gemtext/blob/master/README.rst",
"donate": "https://github.com/flozz/rst2gemtext#support-this-project",
"issues": "https://github.com/flozz/rst2gemtext/issues",
"source": "https://github.com/flozz/rst2gemtext"
},
"split_keywords": [
"restructuredtext",
" rst",
" convert",
" gemtext",
" gmi",
" gemini",
" docutils"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c760f3790a9e72ca2eb790d63ff3875fb5dab7afff6803a558e329316997cadd",
"md5": "e646ab90d64708fcf475c5ae7df5c402",
"sha256": "3397b08ffb5ca3566dbcae592cfd9e08b0c6adece7c0b89f40b6167fd219c32d"
},
"downloads": -1,
"filename": "rst2gemtext-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e646ab90d64708fcf475c5ae7df5c402",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22965,
"upload_time": "2025-08-05T10:26:46",
"upload_time_iso_8601": "2025-08-05T10:26:46.482254Z",
"url": "https://files.pythonhosted.org/packages/c7/60/f3790a9e72ca2eb790d63ff3875fb5dab7afff6803a558e329316997cadd/rst2gemtext-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8c7515fbef111e5689121f7bd129c2468a3044d4270726f69b8aa1c10ddd1d70",
"md5": "688056910c11c87945811380e0d2e1d9",
"sha256": "05ae8e8ab2e426fd3e1afb1a23348c2c30a03804d7daec3ab5c71eee17f5a11b"
},
"downloads": -1,
"filename": "rst2gemtext-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "688056910c11c87945811380e0d2e1d9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24476,
"upload_time": "2025-08-05T10:26:47",
"upload_time_iso_8601": "2025-08-05T10:26:47.587558Z",
"url": "https://files.pythonhosted.org/packages/8c/75/15fbef111e5689121f7bd129c2468a3044d4270726f69b8aa1c10ddd1d70/rst2gemtext-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-05 10:26:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "flozz",
"github_project": "rst2gemtext?tab=readme-ov-file#changelog",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "argcomplete",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "attrs",
"specs": [
[
"==",
"22.1.0"
]
]
},
{
"name": "black",
"specs": [
[
"==",
"22.12.0"
]
]
},
{
"name": "click",
"specs": [
[
"==",
"8.1.3"
]
]
},
{
"name": "colorlog",
"specs": [
[
"==",
"6.7.0"
]
]
},
{
"name": "distlib",
"specs": [
[
"==",
"0.3.6"
]
]
},
{
"name": "docutils",
"specs": [
[
"==",
"0.19"
]
]
},
{
"name": "exceptiongroup",
"specs": [
[
"==",
"1.0.4"
]
]
},
{
"name": "filelock",
"specs": [
[
"==",
"3.8.2"
]
]
},
{
"name": "flake8",
"specs": [
[
"==",
"6.0.0"
]
]
},
{
"name": "iniconfig",
"specs": [
[
"==",
"1.1.1"
]
]
},
{
"name": "mccabe",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "mypy-extensions",
"specs": [
[
"==",
"0.4.3"
]
]
},
{
"name": "nox",
"specs": [
[
"==",
"2022.11.21"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"22.0"
]
]
},
{
"name": "pathspec",
"specs": [
[
"==",
"0.10.3"
]
]
},
{
"name": "platformdirs",
"specs": [
[
"==",
"2.6.0"
]
]
},
{
"name": "pluggy",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "pycodestyle",
"specs": [
[
"==",
"2.10.0"
]
]
},
{
"name": "pyflakes",
"specs": [
[
"==",
"3.0.1"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.2.0"
]
]
},
{
"name": "tomli",
"specs": [
[
"==",
"2.0.1"
]
]
},
{
"name": "virtualenv",
"specs": [
[
"==",
"20.17.1"
]
]
}
],
"lcname": "rst2gemtext"
}
JSON
