Skip to main content

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

Project description

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.

Project details


Release history Release notifications

Download files

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

Files for mdToRst, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size mdToRst-1.1.0.tar.gz (24.5 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page