はじめに
OSSやコードの公開先として定番になっているGitHub。利用している方も多いんじゃないでしょうか。
このGitHub内にwikiが作成できる機能に対する作成備忘録となります。
wiki利用の個人的経緯
勉強の為C言語に合ったデザインパターンの表現という形でQiitaに記事を書く
→ライブラリとして割と自分が使いたい形になってきたなー
→よっしゃ！ちゃんとしたOSSっぽくしよう！
→どうせならQiitaの記事じゃなく、GitHubのコード近くにクラス図くらい欲しいよな～
でもリポジトリに入れると無駄にサイズが重くなるし。何か今までの記事を利用して、まとめサイトを作れないかな～
…そういえばGitHubのwikiがあるな、使ってみるか！
という流れです。
ちなみに作成したWikiはこんな感じ
GitHubとは
本家ホームページより。
GitHubは、ユーザのみなさんからヒントを得て作成された開発プラットフォームです。オープンソースプロジェクトやビジネスユースまで、GitHub上にソースコードをホスティングすることで数百万人もの他の開発者と一緒にコードのレビューを行ったり、プロジェクトの管理をしながら、ソフトウェアの開発を行うことができます。
無料で登録できるgitを利用したソース管理の為のウェブツールです。こちら、OSSをソースコードからビルドしたことのある方は必ず1度は見たことがあると思います。そういったオープンソースプロジェクトや個人の趣味まで、gitを使っていい感じに開発しましょう！というウェブツールとなっています。
GitHubでは何が出来るの？
最初の印象以上に色々なことが出来そうなんですよね。
- ソース管理 無料のgitリポジトリとして活躍します。HTTPS/ssh等のセキュリティ認証が充実しているため、これだけでもいい有用なサーバーですね。
- issue作成 ソースコードに対するタスクをissueで管理できます。記憶力の悪い私はこういう見える化機能大好きです。
- wiki作成 今回紹介する機能です。今日初めて使ってみたレベルですが、特にQiitaの利用者には非常に使いやすいのではないかと思います。
その他プロジェクト作成など色々なことが出来そうですが、ここでは割愛。
Wiki機能
Wikiは、GitHubのリポジトリ内、Code等のタブ内にあります。
自作リポジトリで表示されてない方は、タブ内のSettings->FeaturesのWikiにチェックを入れれば出てくると思います。
最初はREADMEの拡張くらいなものかなと思っていたのですが、普通にこのリポジトリを説明するための簡易ホームページくらいの機能はありそうです。私的には十分すぎる！
形式について
Wikiを記載するフォーマットは無料版を利用している私でも9種類から選択可能です。
何よりもいいのは、Qiitaと同じMarkdown方式もサポートしています。
実際記事の説明をそのまま張り付けてもほぼ同じ内容が表示されるくらい。
その他おそらく一般的であろう形式をサポートしているので、他の何かしらのサイトでライブラリのまとめを行っている方も、スムーズに移行できるのではないでしょうか。
ページの追加について
これが好きに出来るのか不安だったのですが、杞憂でした。普通にページの追加が可能です。
形式にもよるかもしれませんが、作成したページへのリンクも可能なので、非常にまとまった説明サイトとしての機能を果たすことが出来ます。
特殊ページ
ページの追加は可能なのですが、特殊なページがいくつかあります。
これらは便利なページなのですが、名前を変えると普通のページ扱いになりそうなので注意です。
- Home --wikiページを開いた際のTopページです。触ってみると、一見タイトルが変えられそうなのですが、Topページとして扱われなくなりました。
- _Sidebar --常にwikiの横に表示されるページです。目次として便利に利用出来そうです。
- _Footer --常に↓に表示されるページです。自ホームページの宣伝などに使うとよいのではないでしょうか。
Markdownで本当にそのまま使えるの？
Qiitaで出来ることは一通りできるようです。
- サーバー上にある図の張り付け -- Qiitaが利用しているサーバーの図も張り付けられました。
- サイトの参照 -- Qiita同様
[XXX](URL)で出来ます。 - コードの張り付け -- ```で囲めば出来ます。言語対応もされているようです。
の形式じゃなく、画像ドラッグで出てくる*img XXX *の形式(<と>で括られてるやつ)も使えました。
管理方法について
このwikiの記載情報も、GitHubのどこかのリポジトリで管理されているようです。
こんな感じでwikiをcloneして編集している方もいらっしゃいます。
サンプル
作成中のライブラリwikiがこちらになります。
基本作っていたREADMEやQiita記事をがりがり張り付けただけですが、wikiがあるだけでそれっぽくなっていきますね。
Qiita側の記事も張れるので、ベースだけ書いて詳しくは日本語を読め！みたいなスタンスのwikiにも出来そうです。