rn.log

備忘録など

GitBookでWebサイトを作ってGitHub Pagesで公開する方法

はじめに

制作物をまとめた簡素なポートフォリオを作ってみました。

rngtm.github.io

今回のWebサイト、GitBookを利用して作成しています。
GitBook - Document Everything!



今回はGitBookを使用したWebサイトの作り方を紹介します。
そして、作ったWebページをGitHubPagesとして外部に公開する方法も解説したいと思います。


GitBookでWebサイトを作るまで

下のようなテキストファイルから...
f:id:r-ngtm:20200618103126p:plain:w400 f:id:r-ngtm:20200618103154p:plain:w400



以下のようなWebサイトをコマンド一発で生成します。
f:id:r-ngtm:20200618102945p:plain:w350

必要な知識

gitbookで作成したWebサイトを外部へ公開したい場合、以下の知識が必要になります。
1. PowerShellなどのコマンドラインツールの使い方(gitbook実行に必要)
2. Markdownの書き方(Webページを編集するときに必要)
3. Gitの知識(GitHubPagesを使うと、作ったWebページを外部へ公開できます)


GitBookの導入(Windows 10)

Windows 10 で GitBookを使えるようにするまでの手順を紹介します。


npm をインストール

GitBookを使うためには npm というものが必要になります。
公式サイトのインストーラを使ってインストールしましょう。

nodejs.org

f:id:r-ngtm:20200618111435p:plain:w450

インストールが完了すると、PowerShellからnpmコマンドが使えるようになっているはずです。(PowerShellでコマンドを実行してます)
f:id:r-ngtm:20200618111230p:plain:w450




gitbookのインストール

以下のコマンドを実行し、gitbookをインストールします。

npm install -g gitbook-cli


インストールが完了すると、gitbookコマンドが使えるようになるはずです。
f:id:r-ngtm:20200618111844p:plain:w450




Webサイトのひな型作成

gitbookを使ってWebサイトのひな型を作成します。

Webサイト用フォルダの初期化

Webサイトのファイルを置きたいフォルダの中で、以下のコマンドを実行します。

npm init


フォルダを見るとpackage.jsonができていることが確認できます。


f:id:r-ngtm:20200618112333p:plain

Webサイトのひな型の作成

以下のコマンドを実行します。

gitbook init



README.mdと、SAMMARY.mdが作成されます。
f:id:r-ngtm:20200618112616p:plain

これらがWebサイトの元データになります。

Webサイトをローカル表示してみる

以下のコマンドを実行してみます。

gitbook serve


f:id:r-ngtm:20200618113512p:plain

Webブラウザhttp://localhost:4000 へアクセスすると、たった今作成したWebページをプレビュー表示することができます。
f:id:r-ngtm:20200618113651p:plain


Webサイトの元データ

README.mdやSUMMARY.mdを編集することで、Webサイトを編集することができます。
また、Webページを新たに追加したい場合はmdファイルを増やします。

README.md の中身

見出し文字(Introduction)だけが入っています。

# Introduction

README.md はWebサイトで最初に表示されるWebページを記述するためのテキストファイルになります。

SUMMARY.md の中身

見出し文字(Summary)と、README.mdへのリンクが記述されています。

# Summary

* [Introduction](README.md)

SAMMARY.md は画面の左に並ぶメニューを記述するためのテキストファイルになります。

ページを追加してみる

markdown編集用のツール

markdownの編集に適したツールには複数ありますが、今回はVSCodeを使ってmarkdownを編集したいと思います。

code.visualstudio.com

仮ページ(test.md)の追加

markdownという名前のフォルダを作り、その中に test.md ファイルを作成します。
f:id:r-ngtm:20200618142650p:plain

test.mdは以下のような内容にします。

# Test
これはテストページです

README.mdへリンクの追加

README.mdにtest.mdへのリンクを追記してみます。

# Introduction

[テスト用ページ](markdown/test.md)

Introductionのページにリンク付きの文字が追加されます。
f:id:r-ngtm:20200618143753p:plain

SAMMARY.mdへリンクの追加

SAMMARY.mdにtest.mdへのリンクを追記してみます。

# Summary

* [Introduction](README.md)

* [Test](markdown/test.md)

これにより、Webサイト左側のメニューにTestという項目が追加されます。 f:id:r-ngtm:20200618143230p:plain

* [Test](markdown/test.md) という行が、Testという名前でtest.mdへのリンクを貼っている行になります。


Testという項目をクリックすると、test.mdがWebページとして表示されます。
f:id:r-ngtm:20200618144003p:plain

Webサイトのhtmlファイル化

現時点ではmdファイルを作成しただけなので、Webサイトとして公開することはできません。
公開するためには、htmlファイルへコンバートする必要があります。

以下のコマンドを実行します。

gitbook build


コマンドが完了すると、_bookフォルダが作成されます。
f:id:r-ngtm:20200618120006p:plain

_bookフォルダの中を見ると、htmlファイルなどが作成されています。
f:id:r-ngtm:20200618120206p:plain

この_bookフォルダの中身をGitHubへアップロードすることで、Webページを外部へ公開することができます。

予備知識 : _bookではなくdocsへ出力する

htmlファイルが出力されるフォルダ名は変えることができます。

gitbook build (元データが置いてあるディレクトリ) (出力先のディレクトリ)


以下のコマンドを実行すると _bookではなく docsというフォルダへhtmlファイルが出力されます。

gitbook build . docs

f:id:r-ngtm:20200618140740p:plain

Webページのアップロード(GitHub)

作成したWebページをGitHubへアップロードする手順を紹介します。

Gitの環境をインストールしておく必要があります。
git-scm.com

STEP1 : GitHubリポジトリを作る

GitHubにて好きな名前のリポジトリを作ります。
f:id:r-ngtm:20200618130906p:plain

今回はTestという名前でリポジトリを作ってみました。

STEP 2 : WebページのGitリポジトリ

Webページのルートフォルダにて、git initコマンドを実行してGitリポジトリ化します。

まずはgit init でgitを初期化します。

git init

フォルダを見ると.gitフォルダ作成され、gitリポジトリ化したことが確認できます。
f:id:r-ngtm:20200618131324p:plain

STEP 3 : WebページをGitHubへアップロードする

GitHubリポジトリの関連付け

git remote add origin https://github.com/{ユーザー名}/Test.git


ローカルにある全ファイルをバージョン管理の対象として追加

git add .


git addで追加したファイルのコミット

git commit -m "initial commit"


コミットをプッシュ(GitHub上のmasterブランチへ反映される)

git push origin master

参考 : リモートへのプッシュする方法
git pushでリモートリポジトリにプッシュする方法 | TechAcademyマガジン

結果

GitHubリポジトリを確認すると、ローカルのファイルがアップロードされていることが確認できます。 f:id:r-ngtm:20200618132918p:plain

Webページの公開設定(GitHub Pages)

STEP 1 : Settingsを開く

GitHubリポジトリのSettingsの部分をクリックします。
f:id:r-ngtm:20200618133214p:plain

STEP 2 : GitHub Pagesの設定

ページの下のほうにGit Hub Pagesと書かれている項目があります。
f:id:r-ngtm:20200618133444p:plain

Noneと書かれた部分をクリックすると、どのブランチをGitHub Pagesとして公開するかを選ぶことができます。
今回はWebページをmasterブランチにアップしているので、 master branchを選択します。
f:id:r-ngtm:20200618133608p:plain

今回アップしたWebページが https://(ユーザー名).github.io/{リポジトリ名} としてアクセスすることができるようになりました。
f:id:r-ngtm:20200618133852p:plain

今回、Webページのデータは _bookフォルダの中に入っているため、以下のURLでアクセスできます。

https://(ユーザー名).github.io/{リポジトリ名}/_book 

公開設定が反映されるまでにはラグがあるっぽいので気長に待ちましょう。

補足 : docsフォルダに入れたWebサイトは直接読める

_bookというフォルダの中にWebサイトのファイルを入れた場合、

https://(ユーザー名).github.io/{リポジトリ名}/_book 

というURLでアクセスできました。

docsという名前のフォルダに入れた場合は、

https://(ユーザー名).github.io/{リポジトリ名}

というURLでWebサイトにアクセスできるようになります。
こちらのURLのほうがスマートです。


docsを直接表示したい場合、GitHub Pagesの設定にて master branch / docs folder を選ぶ必要があります。
f:id:r-ngtm:20200618135028p:plain

今回アップロードしたTest用のWebサイトは以下から確認できます。
https://rngtm.github.io/Test/