https://github.com/kata198/mdtorst

Tool and library to convert markdown [md] to restructed text [rst] (md to rst)
https://github.com/kata198/mdtorst

convert conveter markdown md mdtorst readme restructed rst text

Last synced: 7 months ago
JSON representation

Tool and library to convert markdown [md] to restructed text [rst] (md to rst)

• Host: GitHub
• URL: https://github.com/kata198/mdtorst
• Owner: kata198
• License: gpl-3.0
• Created: 2017-07-30T03:27:13.000Z (over 8 years ago)
• Default Branch: master
• Last Pushed: 2017-08-10T23:57:07.000Z (over 8 years ago)
• Last Synced: 2025-06-10T04:39:12.684Z (7 months ago)
• Topics: convert, conveter, markdown, md, mdtorst, readme, restructed, rst, text
• Language: Python
• Homepage:
• Size: 78.1 KB
• Stars: 8
• Watchers: 2
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • Changelog: ChangeLog
  • License: LICENSE

Awesome Lists containing this project

README

          
# mdToRst

Tool and library to convert markdown to restructed text (md to rst).

This tool performs some basic conversions to attempt to generate a restructed text document (RST) which renders the same, or as close as possible to a provided markdown (md).

This tool is not perfect, and may require that you write your markdown in a certain way that is apt toward conversion, but it does save a lot of time and prevent error.

Why?

====

It does not make sense and is very error prone to manage two different copies of the same documentation.

I really like markdown, and I absolutely despise restructed text.

Unfortunately, github prefers markdown and pypi will only use RST, so all of my python projects need to have a distinct MD and RST.

The goal here is to simplify things to where you only have to write and maintain a markdown copy (README.md), and after changes you simply run README.md through mdToRst in order to output README.rst .

Usage

=====

	Usage: mdToRst [filename]

		Converts a provided markdown file (.md) to restructed text (.rst)

	If "filename" is provided as "--", the markdown will be read from stdin.

	Example Usage:

		mdToRst README.md | tee README.rst  # Read in README.md, convert to rst, 

											#  and output both to stdout and "README.rst"

		cat README.md | mdToRst         # Pipe in the contents of "README.md", and

										#  output the converted document to stdout

Modification

------------

If you have a usage scenario where mdToRst generates incorrect or suboptimal results, please submit an issue detailing:

* How to reproduce the issue

* What the expected result is

* Why this makes sense

* How to achieve the equivilant in RST

and optionally submit a patch as well.