マークダウンのガイド

特徴

マークダウン（Markdown）は、テキスト形式で文書構造を記述するマークアップ言語である。2004年にジョン・グルーバーによって開発された。

• シンプルな記法：見出しには「#」を、リストには「-」や「*」を使用する。
• 可読性：プレーンテキスト形式であるため、特別なソフトウェアなしで内容を確認できる。
• 論理構造の表現：記号によって文書の階層構造を明示する。
• 習得の容易さ：基本的な記法は短時間で習得できる。
• バージョン管理との親和性：テキスト形式であるため、Gitなどのバージョン管理システムで差分を追跡できる。

主な機能

• 見出し：「# 第1章」、「## 1.1」、「### 1.1.1」のように、「#」の数で階層を表現する。
• 文字装飾：「**太字**」や「*斜体*」で強調する。
• リスト：
  • 箇条書き：「- 項目」または「* 項目」で記述する。
  • 番号付きリスト：「1. 項目」で記述する。
• 引用：「> 引用文」で引用ブロックを作成する。
• コードブロック：バッククォート3つで囲み、言語名を指定する。

  ```python
  print("Hello, World!")
  ```

• 表：パイプ記号（|）とハイフン（-）で構成する。

  | 列1 | 列2 |
  |-----|-----|
  | A   | B   |

• リンク：「[表示文字](URL)」でハイパーリンクを作成する。
• タスクリスト：「- [ ]」でチェックボックス付きリストを作成する。完了した項目は「- [x]」と記述する。
• 脚注：「[^1]」で脚注番号を挿入し、「[^1]: 説明」で脚注内容を記述する。

Pandocを用いた文書変換

Pandocは、異なる文書フォーマット間の変換を行うツールである。マークダウンで作成した文書を、提出先や用途に応じた形式に変換できる。

入力フォーマット

主な入力フォーマットを以下に示す。

• テキスト形式：Markdown、reStructuredText、AsciiDoc、LaTeX、MediaWiki
• 文書形式：Microsoft Word（.docx）、OpenOffice/LibreOffice（.odt）、HTML、EPUB、Jupyter Notebook

出力フォーマット

主な出力フォーマットを以下に示す。

• テキスト形式：Markdown
• 文書形式：PDF、Microsoft Word（.docx）、OpenDocument（.odt）、HTML、EPUB、LaTeX
• プレゼンテーション形式：Microsoft PowerPoint（.pptx）、Beamer（LaTeXベースのプレゼンテーション形式）、RevealJS（HTMLベースのスライド作成フレームワーク）

日本語を扱うときの注意点

日本語文書を変換する際は、以下の点に注意する。

• 文字エンコーディング：UTF-8（BOMなし）を使用する。BOM（Byte Order Mark）はファイル先頭に付加される識別子であり、一部のツールで文字化けの原因となる。
• 日本語フォントの指定：PDF出力時には、XeLaTeX（Unicode対応のLaTeXエンジン）を使用し、日本語フォントを明示的に指定する。

PDF出力時のコマンド例を以下に示す。

pandoc input.md -o output.pdf --pdf-engine=xelatex -V mainfont="Noto Sans CJK JP"

特殊要素の取り扱い

• 数式：LaTeX形式で記述する。
  • インライン数式：「$E = mc^2$」のように「$」で囲む。
  • ディスプレイ数式：「$$」で囲む。例：$$ \sum_{i=1}^n i = \frac{n(n+1)}{2} $$
• コードブロック：バッククォート3つの後に言語名を指定する。

  ```python
  def example():
      return "Hello"
  ```

• 画像：「」の形式で記述する。相対パスを使用すると、フォルダ構成を維持したまま変換できる。

変換後の確認事項

文書変換後は、以下の項目を確認する。

• 文字化けの有無
• 画像の表示
• リンクの動作
• 目次の構成
• レイアウトの崩れ