GitHubを使ってMarkdown文書を５ステップでホームページとして公開する方法



GitHubのウェブページを利用して、情報を共有するプロジェクトが増えています。 Kubernetes プロジェクトの文書や IBM Cloud のマニュアルページも GitHubを使って作成されています。 僕はGitHubの人じゃないですが、この記事で紹介する GitHub pages は、HTMLを覚えなくてもマークダウンで作成できて、テーマを設定によって、見やすい書式へ自動変換される優れたものです。 

このリンクは、https://takara9.github.io/md_docs/ この記事で紹介する方法で作成したものです。



ここで実現することは、以下の５項目です。

* [GitHub Pages](https://help.github.com/articles/what-is-github-pages/) を利用してウェブページを作成
* https://takara9.github.io/md_docs/ の様に、`ユーザー名.github.io/リポジトリ名` でアクセス可能にする
* HTMLではなくマークダウンを使って簡単に作成
* ウェブページのテーマを設定して、見栄えのウェブ良いページに仕上
* 見出し、コードや画像の埋め込み、リンクなど、Markdownの最小限必要な動作を確認



さっそく、ステップを追いながら、ウェブ・ページとして公開するまでの過程をみていきます。



## マークダウンのファイルの準備

自分のPCやMacで、フォルダを作って簡単なマークダウンの文書を作成します。例えば、こんな感じでいかがでしょうか？
次はMacで実行した例です。

~~~
$ mkdir md_docs
$ cd md_docs/
~~~


index.mdというファイルを作成して簡単にウェブページを作成します。 ちょっと文が長いですが、こんな感じです。

```
# マークダウンで書いたページ

人生は、生きてるだけで丸儲け、争わない、楽しみ、チャレンジするそれで、人の役に立てれば最高!


## 中野信子氏「生きてるだけで丸儲け」は生物学的にも正しい

脳科学を通して伝えたいことはシンプルで「生きている者が勝ち！」ということです。

ほとんどの生物の目的というのは「生き延びること」と「子孫を残すこと」なんですね。

ですが人間だけはそうではない。「ひと花咲かせよう！」みたいなのがあって、これがすごい特異的なんですよ。本当は生き延びて生殖するために脳ができたんですけど、でもその脳が発達しすぎてしまったがために「ひと花咲かせよう！」ができちゃうわけです。

私たちが生きているのは、それだけで実績なわけですよ。「生き延びるため」と「生殖するため」ということを考えると、自分がここにいるということは結果なので、ここから先のことは「おまけ」です。

おまけの人生ですから、楽しんでいただきたい。

抜粋 引用元: http://enrique5581.net/nakano-nobuko-life-brain/
```


作成後の状態は、こんな感じです。 一つだけ、拡張子 md で、index.mdファイルが存在している状態です。

~~~
imac:md_docs maho$ pwd
/Users/maho/md_docs
imac:md_docs maho$ ls -al
total 8
drwxr-xr-x  3 maho  staff   102  1  5 09:41 .
drwxr-xr-x  9 maho  staff   306  1  5 09:23 ..
-rw-r--r--  1 maho  staff  1276  1  5 09:38 index.md
~~~





## リポジトリの作成

GitHubにアカウントが無ければ、ユーザー登録してアカウントを作成してくださいね。 GitHubにログインして、右端の+をクリックして、`New repository` を選択します。

![スクリーンショット 2018-01-05 9.44.59.png](https://qiita-image-store.s3.amazonaws.com/0/42829/fd6414b1-d0e8-596e-89a6-36b0c0255e68.png "スクリーンショット 2018-01-05 9.44.59.png")

`Repostory name` にリポジトリ名を半角英数字で登録します。以下の例では`md_docs`とします。 さらに、`Description(optional)`に コメントを入れておけば、作成目的など、後から再参照する時に役立つと思います。

![スクリーンショット 2018-01-05 9.46.50.png](https://qiita-image-store.s3.amazonaws.com/0/42829/45adfceb-1a3b-ed93-336b-928bcd4353a9.png "スクリーンショット 2018-01-05 9.46.50.png")

これで、`Create repository` ボタンをクリックして進めてます。 次の画面は以下の様になっています。` …or create a new repository on the command line` を参考にしながら、GitHubへ登録を進めていきます。

![スクリーンショット 2018-01-05 9.51.18.png](https://qiita-image-store.s3.amazonaws.com/0/42829/9321e2ce-e5fa-d32f-ac7e-6c134031851e.png "スクリーンショット 2018-01-05 9.51.18.png")





## GitHubへの登録

前回のマークダウン文書を作成した後の続きで、GitHubの応答ページを参照しながら、以下を実行していきます。

~~~
$ ls -al
total 8
drwxr-xr-x  3 maho  staff   102  1  5 09:41 .
drwxr-xr-x  9 maho  staff   306  1  5 09:23 ..
-rw-r--r--  1 maho  staff  1276  1  5 09:38 index.md

$ git init
Initialized empty Git repository in /Users/maho/git_homepage/md_docs/.git/

$ git add index.md 

$ git commit -m "first commit"
[master (root-commit) 2e462ca] first commit
 1 file changed, 20 insertions(+)
 create mode 100644 index.md

$ git remote add origin https://github.com/takara9/md_docs.git

$ git push -u origin master
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 871 bytes | 871.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To https://github.com/takara9/md_docs.git
 * [new branch]      master -> master
Branch master set up to track remote branch master from origin.
~~~

これで、GitHubへの登録は完了です。 簡単ですよね。




## ウェブページ設定と確認

これだけだと、普通にGitHubを使う場合と変わりませんから、ウェブページとして表示されません。 次に、`Settings`を選択して、`GitHub Pages`の設定をします。

![スクリーンショット 2018-01-05 9.58.08.png](https://qiita-image-store.s3.amazonaws.com/0/42829/f5f5d6ec-c300-4761-ccf3-81a10e9d8330.png "スクリーンショット 2018-01-05 9.58.08.png")

GitHub pages の場所まで移動して、最初の状態は、`None`になっていますから、`master branch`に変更して `Save`をクリックします。

![スクリーンショット 2018-01-05 9.58.29.png](https://qiita-image-store.s3.amazonaws.com/0/42829/6267c824-9b61-bb20-6396-c10eeb6d854c.png "スクリーンショット 2018-01-05 9.58.29.png")


応答画面は次の様になります。 この表示は準備中（作業中）を意味します。 少し待って、ブラウザで再読み込みします。

![スクリーンショット 2018-01-05 9.58.47.png](https://qiita-image-store.s3.amazonaws.com/0/42829/520e5455-095b-7980-8f64-b0e7ce1389f8.png "スクリーンショット 2018-01-05 9.58.47.png")

次の様に、グリーンの表示でリンクが表示されたら、マークダウンからウェブページの生成完了です。リンクをクリックして内容を確認します。

![スクリーンショット 2018-01-05 9.59.03.png](https://qiita-image-store.s3.amazonaws.com/0/42829/c01d4702-75bc-0bf2-0d90-5c19fa2a144d.png "スクリーンショット 2018-01-05 9.59.03.png")


リンクをクリックすると、マークダウンで書いたページが、HTMLに変換されて、ウェブページになっているのが解ります。

![スクリーンショット 2018-01-05 10.05.38.png](https://qiita-image-store.s3.amazonaws.com/0/42829/c488aa23-2b78-f49f-85ac-0744b01c55b4.png "スクリーンショット 2018-01-05 10.05.38.png")





## テーマ設定

これだけだと、ちょっと、飾り気がなくて、淋しですよ。　テーマを設定して、見易く華やかなページにカスタマイズします。
先ほどの設定画面 `GitHub pages` のなかで、`Choose Thema` をクリックして、テーマの画面を選択します。
![スクリーンショット 2018-01-05 10.09.29.png](https://qiita-image-store.s3.amazonaws.com/0/42829/91e06053-a9c2-a5b7-6392-cc62167aa259.png "スクリーンショット 2018-01-05 10.09.29.png")

例えば、以下の様な感じです。 サムネールをクリックして、`Select thema`ボタンをクリックすることで、テーマの設定が始まります。

![スクリーンショット 2018-01-05 10.10.46.png](https://qiita-image-store.s3.amazonaws.com/0/42829/1a9a3d4a-bf18-9857-8e01-5a4ed019ac6e.png "スクリーンショット 2018-01-05 10.10.46.png")

そして、`GitHub pages`の表示がグリーンに変われば、作成完了です。 この例のアドレスでは、https://takara9.github.io/md_docs/ をクリックして、テーマによって書式が調整されたページを確認します。 注意点として、ウェブのキャッシュが効いているので、ページが更新されません、そこで、再読み込みして見てください。


![スクリーンショット 2018-01-05 10.13.57.png](https://qiita-image-store.s3.amazonaws.com/0/42829/73954d35-0cfa-0c76-28b5-c964375b1119.png "スクリーンショット 2018-01-05 10.13.57.png")

テーマ設定は、GitHubのウェブページから何度でも変更できますから、色々試して好きなテーマを選んでくださいね。



## GitHubページの変更

ウェブページの変更は、エディタでマークダウンのファイルを編集した後に、以下を実行して完了です。 テーマ設定がリセットされるので、もう一度、設定してして完了です。

~~~
git add index.md
git commit -m "update"
git push
~~~

公開して1回目の更新後にpushすると、次のエラー画面が表示されます。 でも、誰かが勝手に変更している訳では無いので、安心してください。 このエラーが表示される理由は、テーマを設定した際に、`_config.yml`というファイルが自動作成されるからです。 このファイルには、テーマ設定の情報が書き込まれています。

~~~
$ git push
To https://github.com/takara9/md_docs.git
 ! [rejected]        master -> master (fetch first)
error: failed to push some refs to 'https://github.com/takara9/md_docs.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.
~~~

対処方法は、`-f` を加えて、再度プッシュすると更新できます。

~~~
$ git push -f
~~~


## 使えるマークダウンの種類と動作

今回資料したテーマのコードが、GitHubの次のリンクにあります。 次の二つを比べると、マークダウンが、GitHubでどの様に変換されて表示されるか、確認する事ができます。

* https://github.com/pages-themes/leap-day/blob/master/index.md
* https://raw.githubusercontent.com/pages-themes/leap-day/master/index.md


---




# まとめ

マークダウンで書いた文書をウェブで公開するには、以下の５ステップで実現できます。 この機能は良いですね。　世のため、人のために、広げて欲しいと思います。

* マークダウン文書を作成
* GitHubにリポジトリを作成
* git push で登録
* GitHub pages を設定
* テーマ設定

さらに、テーマを編集して、高度にカスタマイズしたり、JavaSciptを実行する事もできます。 続きは、次の機会に。。。


さっそく、続編を投稿しましたので、リンクをご紹介します。
[ここまで出来る! GitHubのMarkdownで書くウェブページ　独自テーマの開発](https://qiita.com/MahoTakara/items/e3d88a0d5d128bb07b27)



# 参考資料

1. [GitHubを使って3分でHPを公開する。](https://qiita.com/budougumi0617/items/221bb946d1c90d6769e9)
* [2016年新機能! GitHubのmasterブランチをWebページとして公開する手順](https://qiita.com/tonkotsuboy_com/items/f98667b89228b98bc096)
* [GitHub Pages Basics](https://help.github.com/categories/github-pages-basics/)
* [Jekyll Themes](https://jekyllrb.com/docs/themes/)
* [GitHub Pages themes](https://github.com/pages-themes)