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

2023年08月14日(月) Markdown

社内のナレッジ共有・マニュアル作成を成功させるツール「NotePM」→無料で使ってみる【1分で登録完了】

こんにちは。マニュアル作成・ナレッジ共有ツール「NotePM」ブログ編集局です。

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

関連記事:AsciiDoc記法の書き方(表結合などMarkdownより表現力が高い!)

 

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があったりと、記法は他にも多数あります。ドキュメントはメンテナンス性や、再利用性、低学習コストが大事になりますので、なるべく統一されたものを全員で使うようにしましょう。

 

この資料でわかること

• 個人のノウハウを引き出す社内wikiとは?
• 社内wikiを導入し浸透させるために必要なこと
• 社内wikiツールの選び方

 

NotePM

NotePM

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

NotePMの特徴

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

NotePM
URL: https://notepm.jp/