青葉台旭の投稿用Markdown亜種の仕様
自作の静的サイト・ジェネレーターについて。
基本的には、Markdown記法に準じている。 以下に違いを書く。
フロント・マターがある
三種類の要素をMarkdown解釈対象外としてファイルの先頭に書くことが出来る。 日付、時間、タグ、である。
先頭に空白行があった場合、まず解釈器はそれを削除する。空白行が連続していたら、 そのすべてが無視される。 次に yyyy-mm-dd または、HH:mm または、[aaa, bbb, ccc] という三種類の形式を、先頭から一行ずつ読みながら探す。 yyyy-mm-dd なら、その行は日付を表し、HH:mm なら時間、[aaa, bbb, ccc] ならタグリストということになる。
上記三種の形式のどれでもないと判断され場合、そこでフロント・マターは終わったという事になり、 空白行を含めて、本文すなわちMarkdown形式の解釈に移る。
記事本文の最初の行は、暗黙のうちに記事タイトルとして解釈される
フロント・マターが終わったと解釈すると、次に Markdown の解釈に移るが、この時も先頭の（つまり、 フロント・マターとMarkdown形式の本文との間の）空白行は無視される。空白行が連続していたら、 そのすべてが無視される。
空白行を読み飛ばし、最初に現れた行の先頭にシャープ文字があろうが無かろうが、その行は 記事のタイトルを表すと解釈され、強制的にh2タグに囲まれる。
最初の１行をシャープ記号２つで始めた場合は、明示的にh2すなわち記事タイトルを指定したと 解釈して、本文は２行目以降である。
最初の１行にシャープ記号を付けなかった場合、それは本文の始まりだが、解釈器が勝手に 記事タイトルにした、というストーリーを作った。 つまり最初の１行はタイトルでもあり本文でもある。重複する。
Markdown は、sectionタグを使った入れ子構造としてHTML化される
Markdown は sectionタグを使った入れ子構造としてHTML化される。 h1~h6タグがセクションとセクションを切り分けるセパレータとして利用される。 また h に続く数字はセクションの階層を表すのに使われる。 すなわち、h3タグで始まるセクションを読み込んでいて h4タグに出会うと、解釈器は一つ下の子ノードが 始まったと解釈する。逆に h4で始まるセクションを解釈していて h3 が現れた場合は、そのセクションが 終わって１つ上の第３階層のノードが始まったという事である。 h3 で始まるセクションを読み込んでいて再び h3 に出会えば、それは同じ階層の新しいノードが 始まったという事である。
本文中に h1タグは使えない
h1タグは、ページタイトル「青葉台旭のノートブック」を表示するのに使うため、記事本体では使えない。 また、h2タグは記事のタイトル（この記事で言えば「青葉台旭の投稿用Markdown亜種の仕様」の部分） に使うので、記事本体には使えない。
以上が、おおまかな独自Markdownの仕様である
Jekyll などの静的サイト・ジェネレータは、主にフロント・マター付きの Markdown で書いてそれを 元にHTMLを生成する。そのとき、投稿日などのメタデータの記述にフロント・マターが使われるが、 この部分をなるべく軽くしたいと考えた。
フロント・マターは、yamlなど何らかの汎用データ言語で記述されることが多いが、日付など 必ず書かなければいけない決まり切った記述にも、「date:」などデータ識別用のキーワードを 書かなければいけない。しかし、ホームページに表示する記事専用と割り切ってしまえば、 yyyy-mm-dd 形式の記述があれば、これは投稿日を表しているなと決めつけても良い気がする。 投稿時間、タグのリストなども同様だ。そうすればデータ識別キーワードは必要なくなる。
また、「—」で表される仕切り線も、フロント・マターに決まりきった事しか書かないのであれば 必要ない。日付、時間、タグ配列などの決まりきった書式以外の行が出てきたら、問答無用で 本文が始まったと決めつければ良い。
またタイトル記述も出来るだけ軽くしたい。「title: ……」と書くのも面倒な場合がある。そもそも タイトルを書くことさえ面倒な事もある。そこで、本文の最初の１行が必ずタイトルになるようにした。
それと、github-pages はサーバーにテキストをアップロードすると同時に、出来るかぎり 「jekyll式フロント・マター付きMarkdown」として解釈しようとするようだ。 省略の多い「独自フロント・マター」を記述すると、解釈エラーが起きてpushが停止してしまう。 ファイルの拡張子が「.md」ではなく「.txt」であっても、たとえば最初の行がハイフン三つによる 仕切りだったりと jekyll形式と少しでも近いMarkdownで書くと、やはり解釈が始まってしまうようだ。 そこで、いっそのこと仕切り線は使わないでおこうと思った。
静的サイト・ジェネレーターにおいては、Markdown文書は下書の役目しかないが……
多くの静的サイト・ジェネレーターにとっての最終目的はHTML文書で出力することだ。 Markdown文書は下書に使うものでしかない。
しかし、せっかくMarkdownで書かれたものを公開しないというのも、何だかもったいない。 あるいはサーバー上には置いてあるのに、リンクも張られずに押入れの奥で眠る下書ノート のような扱いになっているのもちょっと寂しい。
それで、Markdownにも専用のindex.htmlを作って（見づらくはあるが）ブラウザで開けるようにした。 ただし平のテキストゆえエンコードはブラウザ側で自動判断してもらうしかない。 文字化けする可能性が大きい。
それでも、トップページ「 aobadaiakira.jp 」からたどりつけるようにしておいた。 まあ、自己満足だ。