AdMaxSDKの使い方はすべてWikiに書いています。

ライブラリなどを作成してGitHubを使って世に公開したときにREADME.mdに使い方すべてを書いてしまうと、とっても読みづらいです。

どんなライブラリか、対応バージョン、インストール方法など簡単に書けるものはREADME.mdに書くで問題ないと思います。

しかし、細かい使い方やAdMaxSDKみたいにあまり使い方がわかっていない人に対して「SDKを用意したから勝手に使ってください。」という姿勢は失礼だと思ったのでWikiにすべてを書きました。

なので、今回はGitHubWikiを公開するまでの流れを書きます。

リポジトリの作成

なにはともあれリポジトリを作成します。

ここは割愛させて頂きます。

Wikiの作成

ではさっそくWikiを作成します。

リポジトリの画面の右にWikiのリンクがあるのでそれをクリックしてください。

リンクはhttp://github.com/${ユーザー名}/${リポジトリ名}/wikiになります。

リンク先に遷移すると以下の画面になると思います。

ScreenShot55

真ん中のCreate the first pageをクリックしてください。

以下の画面になると思います。

ScreenShot56

とりあえず今回は作成することが目的なので、一度右下にあるSave Pageのボタンをクリックして保存します。

すると先程のページが作成されます。

以下の画面になっていると思います。

ScreenShot57

とりあえずこれでWikiの公開は完了です。

ただ、GitHub上(ブラウザ)で編集と更新を続けるのは色々危ないと思います。

先にWikiを完成させといて、ライブラリを公開と同時にWikiを更新したい(あまりないかも知れませんが…)みたいなことができません。

なので、ローカル(自分のPC)で編集してすべて完成させてから公開する手段を紹介します。

ローカルでWikiを編集する

GitHubWikiGitで管理できます。

なのでgit cloneでローカルに落としてきて編集して、git pushで公開するという方法が使えます。

ということで試してみましょう。

git clone

なにはともあれgit cloneWikiのリポジトリを落としてきます。

リンクはgit@github.com:${ユーザー名}/${リポジトリ名}.wiki.gitです。

画面の右側にClone this wiki locallyと書いてある下にリンクがあります。

1
2
3
4
5
6
7
8
9
10
11
$ git clone git@github.com:NinjaAdMax/SampleWiki.wiki.git
Cloning into 'SampleWiki.wiki'...
remote: Counting objects: 3, done.
remote: Total 3 (delta 0), reused 0 (delta 0)
Receiving objects: 100% (3/3), done.
Checking connectivity... done
$ cd SampleWiki.wiki/
$ ls -lah
total 8
drwxr-xr-x 12 hoge fuga 408B 10 8 10:26 .git
-rw-r--r-- 1 hoge fuga 32B 10 8 10:26 Home.md

Home.mdを編集する

Wikiはすべてmarkdownで書きます。

嫌いな人は好きになってください。

ではちょっとHome.mdを編集します。

1
2
3
4
5
6
7
8
diff --git a/Home.md b/Home.md
index 16b7935..e48c230 100644
--- a/Home.md
+++ b/Home.md
@@ -1 +1,3 @@
Welcome to the SampleWiki wiki!
+
+Hello World!!!

add & commit & pushする

ここらへんはすべて他のgitの操作と同じです。

git addしてgit commitしてgit pushするだけです。

ということで公開してみましょう。

1
2
3
$ git add .
$ git commit -m "Update Home.md"
$ git push origin master

git pushの後でリポジトリのWikiページを見ると更新されています。

ScreenShot58

ページを追加してみる

ただMarkdownのファイルを作成してgit addしてgit commitしてgit pushするだけです。

試しにやってみましょう。

1
2
3
4
5
6
7
8
9
10
$ touch Hoge.md
$ echo '# Welcome Hoge Page !!' > Hoge.md
$ cat Hoge.md
# Welcome Hoge Page !!
$ git add .
$ git commit -m "Add Hoge.md"
[master 38d2c53] Add Hoge.md
1 file changed, 1 insertion(+)
create mode 100644 Hoge.md
$ git push origin master

で画面を更新すると右側のPagesというところにHogeという項目が増えています。

これでページの追加が出来るようになりました。

注意点

ファイル名はなんでも大丈夫(僕が確認した時点では日本語も大丈夫でした)なのですが、ファイル名がまんまリンクになります。

つまり今回作ったHoge.mdhttps://github.com/NinjaAdMax/SampleWiki/wiki/Hogeという様になります。

なのでファイル名は出来るだけ英字がよろしいかと勝手に思ってます。

各ページ毎に遷移出来るようにリンクを貼る

ではHomeからHogeページへ遷移できるようにリンクを貼りたいと思います。

リンクは先程もお話した通り、ファイル名がそのままリンクで使われます。

ただ、絶対パス(https://github.com/~)で指定すると確認時がめんどくさいと思うので、相対パスでの指定方法をお教えします。

Home.mdを編集します。

1
2
3
4
5
Welcome to the SampleWiki wiki!
Hello World!!!
[Next Page](Hoge)

という感じです。

特に変わったこともないですね…。

画像を貼る

スクリーンショットを多様することもあるかと思います。

なので画像をWikiページに貼る方法も紹介します。

まずはわかりやすく画像を保存するディレクトリを作成します。

1
2
3
4
5
6
7
8
9
$ mkdir img
$ mv - なにか適当に使いたい画像のパス- img/screen_shot01.png
$ tree
.
├── Hoge.md
├── Home.md
└── img
└── screen_shot01.png
1 directory, 3 files

このようなファイル構成だとします。

そしたら画像を表示したいページ(今回はHoge.md)のファイルを開きます。

以下のように編集してください。

1
2
3
# Welcome Hoge Page !!
![screen_shot01](img/screen_shot01.png "screen_shot01")

なんかコードの時にMarkdownの表示がうまくいきません…。

Hexo特有のやつなのかな…。

とりあえず、Markdownの大原則として各行と行の間に1行空行を挟むということをしてください。

で、いつもの流れでgit add .してgit commit -m "Add screen_shot01.png"git push origin masterなんてやれば画像が表示されます。

サイドバーとフッターを追加する

サイドバーを追加するときは_Sidebar.md、フッターを追加するときは_Footer.mdを追加すれば勝手に表示されます。

ファイルの命名は絶対なので気をつけてください。

公開する前に最終確認をしたい場合

ローカルでWikiを作成してあらかた大丈夫だけど、公開しても問題ないか不安だと思います。

そんな人にgollumを紹介します。

gollum/gollum

これはGitHubのwikiエンジンとなっています。

詳しい紹介と導入方法はREADME.mdgithubのwikiエンジン”gollum”の導入と細かい設定 - yukke::noteを参考にしてください。

とってもわかりやすかったです。

終わりに

Wikiって書き始めはいいんですよね。

これ知っとくと便利だからとかで色々書きたいことが出てくる。

けれど、これを書くとあれも説明しなければならないなという自体が多々発生して、何のためのWikiなのかわからなくなるんですよね。

WikiREADME.mdの役割を考えれば、必然的に書く事が決まってくるかもですね。

以上になります。