pandocでMarkdownからreStructuredTextに変換する手順

pandocを使ってMarkdown形式ファイルをreStructuredText形式ファイルに変換するまでの手順。

pandocとは

Markdown、reStructuredTextを含む様々なフォーマットのドキュメントを、別のフォーマットに変換できるツール。
対応フォーマット等の詳細は公式ドキュメントを参照。

Pandoc - About pandoc

About pandoc

If you need to convert files from one markup format into another, pandoc is your swiss-army knife. Pandoc can convert documents in markdown, reStructuredText, textile, HTML, DocBook, LaTeX, MediaWiki markup, TWiki markup, OPML, Emacs Org-Mode, Txt2Tags, Microsoft Word docx, LibreOffice ODT, EPUB, or Haddock markup to

• HTML formats: XHTML, HTML5, and HTML slide shows using Slidy, reveal.js, Slideous, S5, or DZSlides.
• Word processor formats: Microsoft Word docx, OpenOffice/LibreOffice ODT, OpenDocument XML
• Ebooks: EPUB version 2 or 3, FictionBook2
• Documentation formats: DocBook, GNU TexInfo, Groff man pages, Haddock markup
• Page layout formats: InDesign ICML
• Outline formats: OPML
• TeX formats: LaTeX, ConTeXt, LaTeX Beamer slides
• PDF via LaTeX
• Lightweight markup formats: Markdown (including CommonMark), reStructuredText, AsciiDoc, MediaWiki markup, DokuWiki markup, Emacs Org-Mode, Textile
• Custom formats: custom writers can be written in lua.

日本語ドキュメントは Pandoc ユーザーズガイド 日本語版 - Japanese Pandoc User's Association を参照。

環境

• debian 8.2

手順

pandocをインストール

$ sudo apt install pandoc

pandocの基本的な使い方

簡単な使い方

pandoc -f <入力フォーマット> -t <出力フォーマット> -o <出力ファイル名> <入力ファイル名>

以下各オプション詳細についてman pandocより抜粋。

man_pandoc

-f FORMAT, -r FORMAT, --from=FORMAT, --read=FORMAT
  Specify  input  format.   FORMAT can be native (native Haskell), json (JSON version of native AST), markdown (pandoc's extended markdown), markdown_strict (original unextended
  markdown), markdown_phpextra (PHP Markdown Extra extended markdown), markdown_github (github extended markdown), textile (Textile), rst (reStructuredText), html  (HTML),  doc‐
  book  (DocBook),  opml (OPML), org (Emacs Org-mode), mediawiki (MediaWiki markup), haddock (Haddock markup), or latex (LaTeX).  If +lhs is appended to markdown, rst, latex, or
  html, the input will be treated as literate Haskell source: see Literate Haskell support, below.  Markdown syntax extensions can be individually enabled or disabled by append‐
  ing  +EXTENSION  or -EXTENSION to the format name.  So, for example, markdown_strict+footnotes+definition_lists is strict markdown with footnotes and definition lists enabled,
  and markdown-pipe_tables+hard_line_breaks is pandoc's markdown without pipe tables and with hard line breaks.  See Pandoc's markdown, below, for a list of extensions and their
  names.

-t FORMAT, -w FORMAT, --to=FORMAT, --write=FORMAT
  Specify  output  format.   FORMAT can be native (native Haskell), json (JSON version of native AST), plain (plain text), markdown (pandoc's extended markdown), markdown_strict
  (original unextended markdown), markdown_phpextra (PHP Markdown extra extended markdown), markdown_github (github extended markdown), rst (reStructuredText), html  (XHTML  1),
  html5  (HTML  5),  latex  (LaTeX), beamer (LaTeX beamer slide show), context (ConTeXt), man (groff man), mediawiki (MediaWiki markup), textile (Textile), org (Emacs Org-Mode),
  texinfo (GNU Texinfo), opml (OPML), docbook (DocBook), opendocument (OpenDocument), odt (OpenOffice text document), docx (Word docx), rtf (rich text  format),  epub  (EPUB  v2
  book),  epub3  (EPUB  v3),  fb2  (FictionBook2  e-book),  asciidoc  (AsciiDoc), icml (InDesign ICML), slidy (Slidy HTML and javascript slide show), slideous (Slideous HTML and
  javascript slide show), dzslides (DZSlides HTML5 + javascript slide show), revealjs (reveal.js HTML5 + javascript slide show), s5 (S5 HTML and javascript slide show),  or  the
  path  of a custom lua writer (see Custom writers, below).  Note that odt, epub, and epub3 output will not be directed to stdout; an output filename must be specified using the
  -o/--output option.  If +lhs is appended to markdown, rst, latex, beamer, html, or html5, the output will be rendered as literate Haskell source: see Literate Haskell support,
  below.  Markdown syntax extensions can be individually enabled or disabled by appending +EXTENSION or -EXTENSION to the format name, as described above under -f.

-o FILE, --output=FILE
  Write output to FILE instead of stdout.  If FILE is -, output will go to stdout.  (Exception: if the output format is odt, docx, epub, or epub3, output to stdout is disabled.)

pandocによる変換実行例: md -> rst

実際にpandocコマンドを使ってMarkdownからreStructuredTextに変換してみる。
実行コマンドは以下:

$ pandoc -f markdown -t rst -o README.rst README.md
$

Input (Markdown)

入力のMarkdownファイル(README.md)は README.md template より引用させていただきます。

input(README.md)

## Synopsis

At the top of the file there should be a short introduction and/ or overview that explains **what** the project is. This description should match descriptions added for package managers (Gemspec, package.json, etc.)

## Code Example

Show what the library does as concisely as possible, developers should be able to figure out **how** your project solves their problem by looking at the code example. Make sure the API you are showing off is obvious, and that your code is short and concise.

## Motivation

A short description of the motivation behind the creation and maintenance of the project. This should explain **why** the project exists.

## Installation

Provide code examples and explanations of how to get the project.

## API Reference

Depending on the size of the project, if it is small and simple enough the reference docs can be added to the README. For medium size to larger projects it is important to at least provide a link to where the API reference docs live.

## Tests

Describe and show how to run the tests with code examples.

## Contributors

Let people know how they can dive into the project, include important links to things like issue trackers, irc, twitter accounts if applicable.

## License

A short snippet describing the license (MIT, Apache, etc.)

Output (reStructuredText)

output(README.rst)

Synopsis
--------

At the top of the file there should be a short introduction and or
overview that explains what the project is. This description should
match descriptions added for package managers (Gemspec, package.json,
etc.)

Code Example
------------

Show what the library does as concisely as possible, developers should
be able to figure out how your project solves their problem by looking
at the code example. Make sure the API you are showing off is obvious,
and that your code is short and concise.

Motivation
----------

A short description of the motivation behind the creation and
maintenance of the project. This should explain why the project exists.

Installation
------------

Provide code examples and explanations of how to get the project.

API Reference
-------------

Depending on the size of the project, if it is small and simple enough
the reference docs can be added to the README. For medium size to larger
projects it is important to at least provide a link to where the API
reference docs live.

Tests
-----

Describe and show how to run the tests with code examples.

Contributors
------------

Let people know how they can dive into the project, include important
links to things like issue trackers, irc, twitter accounts if
applicable.

License
-------

A short snippet describing the license (MIT, Apache, etc.)