GitHub Pagesとその他公開方法

[k3kaimu]

現在のd-manualを閲覧する方法としては、唯一GitHub上でmarkdownを閲覧できるだけである。
GitHubにはGitHub Pagesという優れた機能があるので、これを活用すべきである。

また、PDFやEPUBなど他のフォーマットでも配布できるような態勢を作らなければいけない。
そのためには、Markdownの文法をPandocに統一し、Pandocから全て生成させる方法が良い。

結論として、文法をPandocスタイルに改め、PandocによってGFM含めた他のフォーマットへ変換したものを提供すべきである。
また、HTMLやMarkdownとして生成したものについてはGitHub Pagesで閲覧できるようにすべきである。

[k3kaimu]

変換する際にもっとも難しいのは、アンカータグである。
Pandoc拡張なMarkdownでは、ヘッダーに{#foo}のようにタグを設定できるが、GFMではそのような記法は許されていない。

また、GitHub上で(GitHub Pagesではなく)見る場合には、リンク先として[...](foo.md/#bar)のように指定しなければいけない。
逆に1つに結合した場合には、このようなリンクは不正である。

[k3kaimu]

タグについての仕様を、PandocのJSONフィルターを用いて変換すること前提にして裁定する必要がある。

記法について

まず、見出しへのリンクする際に使用する記法は[....](filename.md#level1/level2/.../levelN)とする。

• filename.mdには、たとえばhello_world.mdなど、markdownファイルの名前とする。
• level1, level2, ... levelNについては、見出し名を親子関係にして書く。

以下の文章のhogeに関するタグは、foo.md#ふぉお/B/a/hogeとなる。

// foo.md

# ふぉお

## A

### a

#### hoge

#### bar

### b

## B

JSON-FIlterでの処理

見出し文中にアンダーバー以外の特殊文字が出現した場合には、タグについては、それらすべてをアンダーバー_で置き換えることとする。