|
Python APIを実行する上で多用されているJupyter notebookやGitHubのrepoサイトなどを見るとマークダウン文書に頻繁に遭遇します。例えば、YOLO5の実行ノートブックを見てみれば、マークダウンの利用の仕方がわかります。マークダウン（Markdown）とは、アメリカ合衆国、フィラデルフィア出身のライター・コラムニストであるジョン・グルーバー（John Gruber）によって、2004年に開発された記法のことを指します。マークダウンの記法を知る上で、欠かせないのがマークアップ言語です。マークアップ言語 (markup language)とは、「HTML（HyperText Markup Language）」や「XML（eXtensible Markup Language）」などを指します。
マークアップ言語は、「タグ」と呼ばれる特定の文字列で囲むことで、元の文に構造・装飾などを反映させる言語のことです。しかし、これら「マークアップ」は記述や種類が多く、また覚えることも多いので、専門的な知識を持つ人でなければハードルが高いです。webページなどのデジタル文章を作るときに使うHTML（HyperText Markup Language）などのマークアップ言語を、簡略化できるようにプログラムされた記法がマークダウンです。
markdown 記法の簡単な例 |
日本語Markdownユーザー会の説明を見てみましょう。 文章には「章」や「節」といった「見出し」があります。本文には「段落」や「箇条書き」があります。こんにちのオンライン文書なら「リンク」も使われるでしょう。文章にはこうした「構造」があり、それを明示することで便利に読み書きできます。Markdownの書き方の代表的なルールには
段落は空行で、一行開ける 強調したい部分を ** で囲む 箇条書きは行頭に - リンクは [] でリンクしたい文字を囲って、その直後の () の中にURLを書く
などがあります。Markdownとは、こういったルールの体系、つまり文章の書き方なのです。この例として、以下の文章が載っています。
Markdown（マークダウン）は、**文章の書き方**です。デジタル文書を活用する方法として考案されました。特徴は、 - 手軽に文章構造を明示できること - 簡単で、覚えやすいこと - 読み書きに特別なアプリを必要としないこと - それでいて、対応アプリを使えば快適に読み書きできること などです。Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、最初は [Daring Fireball: Markdown](http://daringfireball.net/projects/markdown/) で公開されました。その後、多くの開発者の手を経ながら発展してきました。
Markdownは、しばしばHTMLの代わりとして使われます。上記の文章をHTMLで書くとすれば以下のようになります。
<p>Markdown（マークダウン）は、<strong>文章の書き方</strong>です。デジタル文書を活用する方法として考案されました。特徴は、</p> <ul> <li>手軽に文章構造を明示できること</li> <li>簡単で、覚えやすいこと</li> <li>読み書きに特別なアプリを必要としないこと</li> <li>それでいて、対応アプリを使えば快適に読み書きできること</li> </ul> <p>などです。Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、最初は <a href="http://daringfireball.net/projects/markdown/">Daring Fireball: Markdown</a> で公開されました。その後、多くの開発者の手を経ながら発展してきました。</p> HTMLを書くときには、<p> や <li> といったHTMLタグをたくさん入力する必要があります。タグを打つことに注意が奪われてしまい、本来の文章作成に集中できません。ふだんの文章作成に気軽に使えるとは言いにくいですね。
この例からも分かる通り、MarkdownからHTMLに変換するのは簡単です。そのためのアプリが多数あります。「HTMLに出力すること」は、Markdownのもっとも一般的な活用法です。作成した文書は拡張子 .md をつけて保存します。
markdown文書を作成し、表示を確認できるエディタの一つにVisual Studio があります。上記のマークダウン文書をVisual Studioで作成します。文書の表示を確認するためには、文書名の上にカーソルを置いて、右クリックします。「プレビューを開く」をクリックすると文書の表示が見られます。または、「space + command + V」(⇧⌘V) キーを押します。
Jupyter Notebookのインストールと使用方法 |
Jupyter Projectにより開発されているJupyter Notebookは、インタラクティブなシェル環境で、ブラウザ上でソースコードを記述し、実行結果を確認しながらドキュメント、数式、画像を含めて一つの「ノートブック」にまとめて、保存することを可能にします。Jupyter NotebookはAnacondaをインストールした時は、一緒にインストールされています。ここでは、Anacondaが使用されていないことを前提にしています。Jupyter notebookが既にインストール済みの時は、この節をスキップして下さい。Terminal上で
$ python3 -m pip install --upgrade pip $ python3 -m pip install jupyterlab jupyter jupyter-console notebook spyder
とコマンドを入力し、Jupyter Notebookをインストールします。python3としているのはpython2.x用のpipを使用しないためです。
どちらのケースでも、Jupyter Notebookを起動するためにはTerminal上で
$ jupyter notebook
とコマンドを入力します。以下の様に、jupyter notebookのダッシュボードがデスクトップに表示されます。
右上に位置する[new]をクリックして、[python3]とします。ノートブックが起動しますので、作成してある[file]を開くか、あるいは、セルに新しいコードを記述します。セルの実行は[cell]をクリックして、[run-cell]します。
Jupyterは、Cellという箱の中に、Codeや説明(Markdown)を記載していき、順次実行させて動かします。色々なiconが表示されていますが、主要な機能は以下の通りです。
これらの機能は使用してみないとわからないので、以下のPythonコードの実行で順次使ってみてください。
枠取りの付いたセルにコードを書き込んで実行する、あるいは、複数個のセルにスクリプトを書き込んで、上から順番にセルのコードを実行します。この作成した（複数個のセルから構成される）ノートをファイルとして保存します。初期名称はUntitledとなっていますので、必要な名前に変えます。ファイルの拡張子はipynbとなっています。保存記号アイコンをクリックして保存すると、homeディレクトリに保存されます。Webブラウザで作業しているので、[File]-[Download as]とクリックすると、NotebookはPCのDownloadsディレクトリにダウンロードされて保存されます。Jupyter Notebookを終了させるときは、ファイルを保存して、[File]-[Close and Halt]とクリックしてください。右上にある[quit]で終了します。また、ターミナルで[Ctrl+c]を入力して、カーネルの作動も終わらせることできます。
Google ColabにおけるMarkdown記法の例 |
Google ColabのMarkdown guideにも簡単な例が出ています。文字のタイプを変化させるケースでは、
//太文字タイプにする **bold text** //イタリック体にする *italicized text* //等幅フォントにする `Monospace` //()内の画像を表示 
などがあります。ヘッダー用の記法として、記号#を用いることができます。
# 第１章 Jupyter Notebookの使用法 # 第２章 マークダウンの利用 ## 第２章の第１節 マークダウンの規則 ### 第２章第１節の第１項 ヘッダの使用 # 第３章 数式の表現
jupyter notebookを開いて、新しいブックを作成して、このコードをコピペして下さい。このセルのコードをMarkdownに変更して下さい。セルをrunして下さい。どのように表示されたでしょうか。
コードを表示するときは、以下のように記述します。以下のコードを次のセルにコピペして、Markdownに変更して、runして下さい。pythonのコードが「print(a)」と表示されます。
```python
print("a")
```
リスト表示を使用するときは以下のように記述します。
//Ordered lists: 1. One 1. Two 1. Three --- //Unordered lists: * One * Two * Three
数式を表示するときは以下のような様式を採用します。HTMLでのLaTex形式とほとんど同一です。以下のコードを次のセルにコピペして同様にrunして下さい。綺麗な数式が表示されたでしょう。
//Equations:
$y=x^2$
$e^{i\pi} + 1 = 0$
$e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i$
$\frac{n!}{k!(n-k)!} = {n \choose k}$
$A_{m,n} =
\begin{pmatrix}
a_{1,1} & a_{1,2} & \cdots & a_{1,n} \\
a_{2,1} & a_{2,2} & \cdots & a_{2,n} \\
\vdots & \vdots & \ddots & \vdots \\
a_{m,1} & a_{m,2} & \cdots & a_{m,n}
\end{pmatrix}$
以下は表を表示するときの記述様式です。
//Tables: First column name | Second column name -------------------|------------------ Row 1, Col 1 | Row 1, Col 2 Row 2, Col 1 | Row 2, Col 2 //Horizontal rules: ---
このコードも前と同じように実行して下さい。最後の行は水平線を引く記述です。
Google Colabでは、Markdownの記法として、Jupyter Notebookのように(MathJax）LaTex表現をサポートしていますが、HTMLタグを許可していません。また、Colabは、絵文字やToDoチェックボックスなどのGitHubの追加をサポートしていません。
Markdownの公式サイトでの表現形式の説明は以下のサイトにあります。