Markdownだけじゃない。開発者向けドキュメント記法まとめ（Textile、RDoc、Org、Creole、AsciiDocなど）

2021年現在、開発者ドキュメントとしてデファクトと言っても過言ではないのがMarkdownでしょう。しかし、Markdownに限らず開発者が利用しているドキュメントフォーマットがあります。

今回はそんなフォーマットをまとめて紹介します。

Textile

TextileはDean Allen氏によって2002年に開発されました。自身が開発したTextpatternというCMSで利用するフォーマットとして開発されています。TextileはMarkdownの記法に影響を与えたとされています。拡張子は .textile です。

記法例です。

h2. Textile

* is a _shorthand syntax_ used to generate valid HTML
* is *easy* to read and *easy* to write
* can generate complex pages, including: headings, quotes, lists, tables and figures

Textile integrations are available for "a wide range of platforms":/article/.

Textile Markup Language Documentation

関連記事：Textile記法の書き方（軽量マークアップ言語）

RDoc

RDocはDave Thomas氏によって開発された記法です。特にRubyのために開発されています。たとえばRubyのソースコードを解析し、オブジェクトやメソッドを構造化したページ群を生成するといった機能があります。RDocはRubyコア機能の一部として含まれています。拡張子は .rdoc です。

記法例です。

= \RDoc - Ruby Documentation System

home :: https://github.com/ruby/rdoc
rdoc :: https://ruby.github.io/rdoc
bugs :: https://github.com/ruby/rdoc/issues
code quality :: {<img src="https://codeclimate.com/github/ruby/rdoc/badges/gpa.svg" alt="Code Climate">}[https://codeclimate.com/github/ruby/rdoc]

== Description

RDoc produces HTML and command-line documentation for Ruby projects.  RDoc
includes the +rdoc+ and +ri+ tools for generating and displaying documentation
from the command-line.

rdoc 6.0.4 Documentation

関連記事：RDoc記法の書き方（Rubyで使われるドキュメント記法）

Org

Emacsのorg-modeの中で使われている記法です。2003年にCarsten Dominik氏が自分用にと作成した記法です。Emacsに標準搭載されていることもあり、Emacs利用者の中にはorg-modeを愛用する方も多いです。拡張子は .org となっています。

記法例です。

* Heading
** Sub heading

Paragraphs are separated
by a blank line.

-----

Five dashes is a horizontal rule.

Simple markup produces *bold*
and /italic/ text. There's also
~code~, and other markups.

Here is a link to the
org [[https://orgmode.org/][homepage]].

Org mode for Emacs

Creole

Creoleは各種Wiki間における記法の違いをなくすために生まれた共通記法です。異なるWikiエンジン間で簡単にコンテンツを利用できるのが目標です。拡張子は .creole です。

記法例です。

= 見出し 第1レベル =

* //強調 (斜体)//
* **太字**
* **//太字 斜体//**, //**斜体 太字**//
* {{{等幅}}}

* [[FrontPage]]

Home

MediaWiki

MediaWikiはWikipediaで使われている記法です。世界最大の百科辞典サイトなので、使ったことがある人も多いのではないでしょうか。Wiki記法ではありますが、独自の拡張が含まれています。拡張子は .mediawiki であることが多いです。

= レベル 2 =

''斜体''
'''太字'''

----

* それぞれの行を、
* アスタリスク[[Wikipedia:asterisk|asterisk]] (*)で始めます。

;項目 1
: 定義 1
;項目 2
: 定義 2-1
: 定義 2-2

Help:書式整形 – MediaWiki

関連記事：MediaWikiの書き方（Wikipediaで利用されている記法）

reStructuredText

reStructuredTextはDocutilsとSphinxで利用されている記法になります。Pythonのソースコード中に書かれていることが多いです。ソースコード中に書かれていたとしても可読性が高いように工夫されています。拡張子は .rst です。

記法例です。

セクション・ヘッダ
==================

サブセクション・ヘッダ
----------------------
リスト:

- 箇条書きリストの項目
- 2つ目
  - サブ項目
- 3つ目

reStructuredText入門 — Sphinx documentation

AsciiDoc

AsciiDocは2002年にStuart Rackham氏によって開発されました。人が読みやすいドキュメントとして開発されています。オライリーの一部書籍ではAsciiDocによって書かれています。拡張子は .adoc です。

記法例です。

= My Article
J. Smith

https://wikipedia.org[Wikipedia] is an
on-line encyclopaedia, available in
English and *many* other languages.

== Software

You can install 'package-name' using
the `gem` command:

 gem install package-name

== Hardware

Metals commonly used include:

* copper
* tin
* lead

AsciiDoc Home Page

POD

PODはPlain Old Documentationの略で、主にPerlで利用されているドキュメント記法になります。Perlモジュールなどの文書でも利用されています。拡張子は .pod ですが、通常はPerlのソースコード中に埋め込まれて記述されることが多いです。

記法例です。

=head1 名前

podsample - POD文書のサンプル

=head1 概要

    $here->isa(Piece::Of::Code);
    print <<"END";
    このインデントされたブロックはフォーマットされた
    コードか指示のため、走査されずに、スペースは保持
    されるでしょう。
    END

=head1 記述

これは標準テキストです。これはB<ボールド>、I<イタリック>、
C<$リテラルコード>のテキスト書式を
内部に含んでいます。

perlpod – the Plain Old Documentation format – Perldoc Browser

まとめ

今回紹介した各記法はGitHubのREADMEとして利用できるフォーマットになります。PODを拡張したMODがあったりと、記法は他にも多数あります。ドキュメントはメンテナンス性や、再利用性、低学習コストが大事になりますので、なるべく統一されたものを全員で使うようにしましょう。

NotePM

NotePM（ノートピーエム） は、ナレッジ共有に特化した「社内版ウィキペディア」です。検索に強く、情報を整理しやすいのが特徴です。Markdown対応で、CommonMarkに準拠しています。

NotePMの特徴

マニュアル作成、バージョン管理、ファイル共有機能
強力な検索機能。PDFやExcelの中身も全文検索
社内FAQ / 質問箱、社内ポータルとしても活用できる
銀行、大学も導入している高度なセキュリティ。安全に情報共有できる

NotePM
URL: https://notepm.jp/