Help us understand the problem. What is going on with this article?

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

More than 3 years have passed since last update.

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をインストール

# aptitude install pandoc
以下の新規パッケージがインストールされます:
  liblua5.1-0{a} libyaml-0-2{a} pandoc pandoc-data{a}
更新: 0 個、新規インストール: 4 個、削除: 0 個、保留: 0 個。
4,814 k バイトのアーカイブを取得する必要があります。展開後に 39.0 M バイトのディスク領域が新たに消費されます。
先に進みますか? [Y/n/?] y
取得: 1 http://ftp.jp.debian.org/debian/ jessie/main liblua5.1-0 amd64 5.1.5-7.1 [108 kB]
取得: 2 http://ftp.jp.debian.org/debian/ jessie/main libyaml-0-2 amd64 0.1.6-3 [50.4 kB]
取得: 3 http://ftp.jp.debian.org/debian/ jessie/main pandoc-data all 1.12.4.2~dfsg-1 [202 kB]
取得: 4 http://ftp.jp.debian.org/debian/ jessie/main pandoc amd64 1.12.4.2~dfsg-1+b14 [4,453 kB]
4,814 kB を 21秒 秒で取得しました (221 kB/s)
以前に未選択のパッケージ liblua5.1-0:amd64 を選択しています。
(データベースを読み込んでいます ... 現在 38916 個のファイルとディレクトリがインストールされています。)
.../liblua5.1-0_5.1.5-7.1_amd64.deb を展開する準備をしています ...
liblua5.1-0:amd64 (5.1.5-7.1) を展開しています...
以前に未選択のパッケージ libyaml-0-2:amd64 を選択しています。
.../libyaml-0-2_0.1.6-3_amd64.deb を展開する準備をしています ...
libyaml-0-2:amd64 (0.1.6-3) を展開しています...
以前に未選択のパッケージ pandoc-data を選択しています。
.../pandoc-data_1.12.4.2~dfsg-1_all.deb を展開する準備をしています ...
pandoc-data (1.12.4.2~dfsg-1) を展開しています...
以前に未選択のパッケージ pandoc を選択しています。
.../pandoc_1.12.4.2~dfsg-1+b14_amd64.deb を展開する準備をしています ...
pandoc (1.12.4.2~dfsg-1+b14) を展開しています...
man-db (2.7.0.2-5) のトリガを処理しています ...
liblua5.1-0:amd64 (5.1.5-7.1) を設定しています ...
libyaml-0-2:amd64 (0.1.6-3) を設定しています ...
pandoc-data (1.12.4.2~dfsg-1) を設定しています ...
pandoc (1.12.4.2~dfsg-1+b14) を設定しています ...
libc-bin (2.19-18+deb8u1) のトリガを処理しています ...

#

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による変換実行例

実際に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.)
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away