GitHub から Markdown だけ切除してみた
2023年05月25日 木曜日
CONTENTS
お久しぶりです。ふぇにっくちゅん です。
いきなりですが、みなさんは普段文章を書くときに、Markdown を利用していますか？
ふぇにっくちゅんは、ほとんどのシーンで Markdown で文章を書いています。
Markdown は簡単な構文を覚えるだけでよく、書いた文章をきれいに整えて表示できるようになります。
ここで、文章を書く方々に質問です。
文章を書くために HTML なんて書きたいですか？
（書きたくない）
文章を書いて公開するだけなのに、WordPress を運用したいですか？
（DBなんて運用したくない）
文章の公開と非公開という単純な閲覧制限の機能だけで物足りますか？
（柔軟かつ適切に設定したい）
今回紹介するのは、これらの疑問を解決したアプリです。
このアプリの名称は、cats_dogs（CAT’S DOCument System）と呼びます。
cats_dogs は、Markdown を HTML で表示できるアプリです。
しかし、この cats_dogs は単なる Markdown ビューアではありません。
上記の疑問を解消するための、便利な機能が実装されています。
cats_dogs は書いた文書を共有する、という観点で実装しているため、閲覧する権限を細かく操作できます。
たとえば、 Markdown 上の一部を特定の人だけに表示させる、ということができるようになります。
このアプリを使用すれば、 Markdown だけで社内のポータルサイトや組織の専用サイト、プロジェクト専用の Web サイトなどを作成できます。
今回は利用したい人向けに Youtube で構築支援のためのデモを用意していますので、こちらも併せて御覧ください。
それでは、以降にアプリの概要を紹介していきます。
まずは、Markdown の歴史を紹介し、その後 cats_dogs の全体像を見てみましょう。
Markdown の歴史と方言
“文章を書く”目的の場合、構文やフォーマットにできるだけ縛られたくありません。
たとえば、HTML は文章をコンピュータで整えて表示するための構文であるため、人間には辛いわけです。
この場合、明らかに不便な縛りを強いられながら、文章を書くことになります。
この不便な縛りから、ある程度開放してくれたのが Markdown です。
しかし、 Markdown は良いことだけではなく、書きやすさの代わりに厄介なことがあります。
Markdown で書いた文章なのに、アプリやサービスによって、想定した表示がされないという経験がありませんか？
実は Markdown には方言が存在しており、方言によって表示がうまくできない厄介事が付きまといます。
なぜこのような厄介事が起きているか？は、Markdown の歴史を調べると視えてきます。
Markdown の歴史は、John Gruber をはじめとし、2004年に単純なブログを書くための構文として作られた、というところから始まります。
本記事では、これを初期の Markdown と呼び、時代が進むにつれて Markdown の人気が出てきたようです。
しかし、初期の Markdown は、仕様が曖昧と主張され、2012年に CommonMark として仕様を統一する動きがでてきます。
この CommonMark のおかげで、最近は方言に悩まされにくくなっているわけなのですが、解決には至っていません。
方言以外にも、構文としての完成度も十分ではないためです。
たとえば、GitHub では、GitHub Flavored Markdown Spec のように CommonMark をベースとして、物足りない構文を補完しています。
これは現代でも、実装に必要な仕様や、 Markdown として必要な機能は未だ発展途上ということが感じ取れます。
統一化という流れの一方で、初期の Markdown は、読みやすく書きやすいを思想に作られたものです。
これを追求すると、ハッキリとした仕様を提示することがナンセンスではないか？ということが想像できます。
Markdown は、書きやすさという感覚的なものを扱うため、時代や個人によって変化していくはずです。
つまり、初期の Markdown は、それを考慮して あえて 実装に必要な仕様を曖昧にしていたのではないか？と感じ取れるわけです。
過去の歴史を紹介したとおり、Markdown の方言や構文の種類について何が良いのか？という話題は厳密には決められない可能性があります。
このことが、Markdown の方言が存在する理由の一つです。
つまり、方言に悩まされることは厄介なのではなく、方言が存在することが Markdown の特性ということになります。
しかし、できるだけ厄介事からは縁が遠い方が良いです。
そのため、勝手ながら ふぇにっくちゅん が選んだ Markdown の仕様は、GitHub Flavored Markdown としています。
これは、私自身がエンジニア界隈にいるため、GitHub との相性が良いことが、ベターな選択であるというだけです。
そのため、cats_dogs の方言は GitHub になります。
cats_dogs の全体像
それでは、cats_dogs が実際にどのような表示になるか、サンプルを紹介します。
# Markdown のサンプル ここに好きな文章を書く。 ## リストもできるよ - リスト1 - リスト2 - リスト3
cats_dogs は Web アプリケーションであるため、Web サーバに配置して動作させます。
そのため、他者がブラウザで閲覧できるため、情報の共有も簡単にできます。
バックアップや下書きは git を駆使すれば可能です。
また、以前公開した ngx_auth_mod との相性も良くできています。
ngx_auth_mod は URL のパスごとに細かく閲覧制限をかけることができます。
cats_dogs はそれに加え、閲覧者によって表示内容を変更できるようになっています。
つまり、ユーザやグループに応じて、文書の表示内容を変更することができます。
実際に見たほうがわかりやすいので、以下のサンプルを確認してください。
同じ Markdown ファイルに、複数の表示内容を記述できるところがポイントです。
以下のサンプルは、管理者のグループ（admin）と一般ユーザのグループ（user）に属する人に応じて、表示内容を変更するものです。
# 表示内容が閲覧者によって変わるサンプル
{{if in_group "admin" -}}
あなたは 管理者 です。
{{- end}}
{{if in_group "user" -}}
あなたは 一般ユーザ です。
{{- end}}
グループ単位だけでなく、ユーザ単位などの設定もできます。
cats_dogs への思い
本記事では、cats_dogs アプリの概要を説明してきましたが、このアプリの開発には様々な思いで作っています。
そのため、たくさんの資料を事前に用意しています。
以下の資料の概要を参考に、読者の皆さんが必要と感じるものを選択して、cats_dogs を使ってみてください。
- アプリの構築支援動画
- アプリの機能概要
- アプリの仕様書
- アプリの裏側（下記参照）
大きく4つのパートに分けています。
まず「アプリの構築支援動画」は、とにかく早く使ってみたいという方向けに、cats_dogs が動作する環境を構築するための動画を用意しています。
また、ここでは cats_dogs の他に cats_ample というデモ用のサンプルデータを使うことが前提となっています。
つぎに「アプリの機能説明」です。
ここでは、次に説明する「アプリの仕様書」を読む前のワンステップとして、アプリの概要や設定ファイルなどの話題を解説しています。
いきなり「アプリの仕様書」を読むのが辛い方は、先にこちらを読むとスムーズに進めることができます。
また「アプリの機能概要」で説明する内容は、「アプリの構築支援動画」で作成したでも環境を元に解説しています。
つぎに「アプリの仕様書」です。
これは cats_dogs の細かな仕様が記載されている資料です。
コードと一緒に同封されていますが、cats_dogs はカスタム性が高いため、いきなり全てを把握するのには苦労すると思います。
この資料を読むタイミングは、cats_dogs を自分なりに使いこなしていく前 に読むとよいです。
デモ環境を使いながら、この仕様書に書いてあることを試していくと、使い道の幅が広がると思います。
最後に「アプリの裏側」として、cats_dogs に纏わる話題をブログとして用意しています。
cats_dogs の使い方のヒントにもなるため、読者の皆さんが気になるタイトルの記事を御覧ください。
おわりに
ふぇにっくちゅんは、この cats_dogs を社内で活用しています。
たとえば、以前の「情報を流れに乗せよう：セキュリティ調査の共有方法」で触れた CATSHAND のシステムの根幹として利用しています。
CATSHAND はネットワーク情報に関する調査ドキュメントを扱うため、ネットワーク情報の検索システムである CHAGE と連携させることで実用化さています。
つまり、ドキュメントを活かせるような 検索 の機能を実装し、組み合わせました。
例として CATSHAND を簡単に紹介しましたが、ドキュメントの活用目的は各々異なると思います。
皆さんも cats_dogs をベースに、ドキュメントを活かせるような機能を実装してみてはいかがでしょうか？
それでは、良き Markdown life を<3
