Jupyter Notebookで作成したMarkdownドキュメントをGitHubで公開する

##:leo: この記事の目的

Jupyter Notebookでは、プログラムを実行するための用途だけに限らず、**Markdown**機能を使用して、数式を記載したり、表や見出しの挿入、文字装飾、画像貼り付けなどを行い、プレゼン資料として作成することができます。
さらに、このように作成した資料をGitHubに移植することで、インターネット上で公開することもできます。

ここでは、Jupyter NotebookでのMarkdownを使用したドキュメント作りから、**GitHubでの公開**までの手順を説明します。

今回は事例として簡単なプレゼン資料を実際に作成しながら、その手順をご紹介します。


##:leo: Jupyter NotebookでMarkdownドキュメントを作成する

### 1. Markdownとは

一般的にJupyter Notebookでは、cell(セル)と呼ばれる段落枠の中にプログラミングを行い、それを実行して結果を表示するという使い方をします。

下図のように、セルの機能を標準の「Code」から「**Markdown**」に変えることで、Markdownドキュメントとして使用することができます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/ade28cfa-e3e9-5b95-44b9-6ef63dc88c23.png)
Markdown機能を使用すると、文章に様々な装飾を施すことができます。

### 2. Markdownの使い方

セルの機能をMarkdownに設定したら、セルの中に文章を書きます。
例えば以下のような簡単な文章を記載した場合、
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/de378907-eac7-e749-b179-385c9f582f30.png)
文章が完成したら、上図赤枠の矢印ボタンを押下することで、以下のようにMarkdownドキュメントに変わります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/d55b2023-dfe7-291d-b426-579f2bbcf854.png)
文章やMarkdownの装飾を修正する場合は、このドキュメントをダブルクリックすると、先ほどの編集セルに戻ります。


### 3. 見出し

見出しの装飾について確認します。
見出しは**#記号**で記載します。
下図は、見出し1から見出し5まで記載した例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/8c330220-eb1c-998d-65ee-2a1d590d9d2e.png)
実行結果は以下の通りです。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/2a77f777-4b29-be6a-45ea-d8795f02c22b.png)

### 4. 文字装飾

太文字、斜体、打消し線の装飾ができます。

|装飾  |書き方|
|:---:|:---:|
|太文字|**(アスタリスク2つ)|
|斜体(イタリック)|*(アスタリスク1つ)|
|打消し線|~~(チルダ2つ)|

以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/13bbc26a-150b-ddf4-70ca-f1c628b4daf6.png)

### 5. 箇条書き

箇条書きの行頭文字は**ハイフン**を使用します。
また、TABまたはスペース4文字で段落を落とすことで子段落、孫段落を入れ子にすることができます。
ハイフンの後にスペース1文字を入れることを忘れないでください。
また、行頭文字の種類は自動的に割り振られます。

以下の文章を記載しました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/84f35b49-d334-6cb1-17b0-c5c42cedb5b0.png)
以下、Markdownドキュメントの実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/2981b7a6-6a71-d81f-f947-77626a33623c.png)

### 6. 番号付きリスト

箇条書きの行頭文字を連番数字にしたい場合、以下のような番号付きリストを使用することができます。
行頭文字の文字種類は自動的に割り振られます。
行頭文字の後にスペース1文字を入れることを忘れないでください。
元の文章につける行頭文字は同じ数字を付けると自動的に連番に変わります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/1e6d05a7-ae47-ad79-8cfc-f4f1b1283457.png)
以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/44dde468-4874-3b34-d065-c1ff234dc64c.png)

また、任意の番号から(途中の番号から)開始する場合は、その番号を行頭文字に付けることで表示することができます。

元の文章
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/eff356cd-0fb3-943f-d583-42e2f8cc8c7f.png)
以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/36bc98e7-3f5c-9740-3da9-c7f505285e02.png)

### 7. 表

表を記載することができます。
表の作成方法は、以下の文章を参考にしてください。
項目1は**左揃え**、項目2は**中央揃え**、項目3は**右揃え**を設定しています。

元の文章
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/b92771ad-c067-57cc-ea9c-e335b8edc8e6.png)
以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/9644ea98-d92f-43d2-b46b-c87f84c744ad.png)

### 8. 数式

数式は以下の記号で記載することができます。
数式の記載方法は**TeX**に準じます。

|記号|使い方|
|:--:|:---|
|$|前後を$文字で囲む。インラインで数式を使用する場合。|
|$$|開始行と終了行を$$文字で囲む。新たに段落を作成して数式を記載する場合。|

元の文章
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/44894019-e34a-8ad7-df66-a13c4cd30916.png)
以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/6ce815e6-cd26-fd9c-674c-33d44349581a.png)

### 9. 画像

画像挿入するには、以下のように記載します。

` ![代替文字列](画像パス) `

画像パスとは、Jupyter Notebookのドキュメント(Jupyter Notebook形式ファイル：.ipynb)が存在するディレクトリからの画像のパスを記載します。

例えば、元の文章が以下の場合、
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/34e00234-73d1-528f-c9d6-715c3a14a9fd.png)
現在編集中のドキュメントと同階層に画像ファイル「sin_pic_sample.JPG」を配置しておく必要があります。
下図は、画像ファイル「sin_pic_sample.JPG」(赤枠)を配置した例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/6e18de56-4c45-2e84-4c11-f760738e273d.png)
Markdownを実行すると画像が表示されます。
画像が存在しない場合や表示に不具合がある場合、代替文字が表示されます。

### 10. 改行

Markdownで表示された文章内で改行を設定するには、**半角スペース2文字**を挿入します。
半角スペースは見えないため分かりにくいため、Markdown表示で確認してください。
以下は赤枠部分に半角スペース2文字を挿入した例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/1f0bfd55-df86-1de4-8fac-934c39a21c20.png)
Markdownを実行すると以下のように改行されて表示されます。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/096706f2-17ff-f30a-4d57-4ab8c32e5af4.png)
半角スペースがない場合は、以下のように改行されません。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/7502471f-9d30-de90-33ae-feaaeba692c0.png)

### 11. 引用

引用は**>**記号を使用します。

元の文章
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/434b83aa-0ee5-dcf3-aaf3-a259aba9c5ea.png)
以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/dd83f52d-6aba-fb3e-d507-7a5a00bdc23b.png)

### 12. リンク

文字列にリンクを設定する場合は以下のように記載します。

` [表示文字列](リンクURL) `

以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/c3c4a7b2-4876-07cc-5e9e-960fa5d6de17.png)

### 13. 水平線

水平線はアンダースコア、アスタリスク、ハイフンなどを3文字以上記述することで表示します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/7eff85df-9e8a-31f7-9333-c2effdaf0281.png)
以下、実行例です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/ae950868-ce8e-1a9b-752e-d32009bd4f2d.png)


##:leo: GitHub上でドキュメントを公開する

作成したJupyter NotebookドキュメントをGitHubに移植して公開する手順を確認します。

### 1. GitHub上に公開(public)リポジトリを作成する

GitHub上でドキュメントを公開する場合は、**公開(public)リポジトリ**を作成する必要があります。すでに存在する場合は作成不要ですが、もし無い場合は以下の手順で作成してください。

####(1)新規にリポジトリを作成する

GitHubのサイトにログインし、右上のメニューから「New repository」を選択します。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/676b2e23-5046-3c13-4a5b-9685b7bff28f.png)

####(2)リポジトリの設定をする

作成画面でリポジトリ名と公開(public)の設定を行います。
下図のように、赤枠1にリポジトリ名を入力し、赤枠2で「Public」を選択します。
その後、最下部の「Create repository」ボタンを押下します。
今回はリポジトリ名を"pubdocs"としました。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/5a921b03-cb49-55fb-572d-19c6670a7057.png)

### 2. Jupyter NotebookドキュメントファイルをGitHubへ格納する

リポジトリの作成が終わったら、Jupyter Notebookで作成したドキュメント(Jupyter Notebook形式ファイル：.ipynb)を公開リポジトリへ格納します。
もしJupyter Notebookドキュメントで画像ファイルも引用していた場合は、画像ファイルも一緒に格納します。

格納する方法は、リポジトリへファイルを追加後にcommit、pushしても良いですし、GitHub画面上でUpload機能を使用してファイルをUploadしても良いです。

下図はリポジトリへファイルを格納した際の例です。ipynbファイルと画像ファイル(JPG)を格納してあります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/399135/ad699de5-bfd7-27c6-fe4b-27e80ccea83e.png)

### 3. ドキュメントを公開する

ドキュメントを公開リポジトリへ格納した時点で、インターネット上に公開されます。
公開されたページのURLを取得する際には、GitHubの当該ページを表示させ、ブラウザのアドレスバーからURLをコピーすれば取得できます。

今回作成したドキュメントは実際に公開しています。
こちらからご参照頂けたら幸いです。

■三角関数(sin)のグラフ
https://github.com/TetsuroTabataOuterproject/pubdocs/blob/main/MarkdownPresen.ipynb



##:leo: 関連情報

三角関数(sin)のグラフ
https://github.com/TetsuroTabataOuterproject/pubdocs/blob/main/MarkdownPresen.ipynb


##:leo: ご意見など

ご意見、間違い訂正などございましたらお寄せ下さい。