Welcome to Mashykom WebSite


Markdown文書の記述方法

　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の書き方の代表的なルールには

  1.  
  2. 段落は空行で、一行開ける
  3. 強調したい部分を ** で囲む
  4. 箇条書きは行頭に -
  5. リンクは [] でリンクしたい文字を囲って、その直後の () の中にURLを書く
  6.  

などがあります。Markdownとは、こういったルールの体系、つまり文章の書き方なのです。この例として、以下の文章が載っています。

  1. Markdown（マークダウン）は、**文章の書き方**です。デジタル文書を活用する方法として考案されました。特徴は、
  2.  
  3. - 手軽に文章構造を明示できること
  4. - 簡単で、覚えやすいこと
  5. - 読み書きに特別なアプリを必要としないこと
  6. - それでいて、対応アプリを使えば快適に読み書きできること
  7.  
  8. などです。Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、最初は [Daring Fireball: Markdown](http://daringfireball.net/projects/markdown/) で公開されました。その後、多くの開発者の手を経ながら発展してきました。

Markdownは、しばしばHTMLの代わりとして使われます。上記の文章をHTMLで書くとすれば以下のようになります。

  1. <p>Markdown（マークダウン）は、<strong>文章の書き方</strong>です。デジタル文書を活用する方法として考案されました。特徴は、</p>
  2.  
  3. <ul>
  4. <li>手軽に文章構造を明示できること</li>
  5. <li>簡単で、覚えやすいこと</li>
  6. <li>読み書きに特別なアプリを必要としないこと</li>
  7. <li>それでいて、対応アプリを使えば快適に読み書きできること</li>
  8. </ul>
  9.  
  10. <p>などです。Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、最初は <a href="http://daringfireball.net/projects/markdown/">Daring Fireball: Markdown</a> で公開されました。その後、多くの開発者の手を経ながら発展してきました。</p>
  11. 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上で

  1.  
  2. $ python3 -m pip install --upgrade pip
  3. $ python3 -m pip install jupyterlab jupyter jupyter-console  notebook  spyder
  4.  

とコマンドを入力し、Jupyter Notebookをインストールします。python3としているのはpython2.x用のpipを使用しないためです。

　どちらのケースでも、Jupyter Notebookを起動するためにはTerminal上で

  1.  
  2. $ jupyter notebook
  3.  

とコマンドを入力します。以下の様に、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にも簡単な例が出ています。文字のタイプを変化させるケースでは、

  1. //太文字タイプにする
  2.  
  3. **bold text** 
  4.  
  5. //イタリック体にする
  6.  
  7. *italicized text* 
  8.  
  9. //等幅フォントにする
  10.  
  11. `Monospace`  
  12.  
  13. //()内の画像を表示
  14.  
  15. ![An image](https://www.google.com/images/rss.png) 
  16.  

　などがあります。ヘッダー用の記法として、記号#を用いることができます。

  1.  
  2. # 第１章　Jupyter Notebookの使用法
  3.  
  4. # 第２章　マークダウンの利用
  5.  
  6. ## 第２章の第１節　マークダウンの規則
  7. ### 第２章第１節の第１項　ヘッダの使用
  8.  
  9. # 第３章　数式の表現
  10.  

　jupyter notebookを開いて、新しいブックを作成して、このコードをコピペして下さい。このセルのコードをMarkdownに変更して下さい。セルをrunして下さい。どのように表示されたでしょうか。

　コードを表示するときは、以下のように記述します。以下のコードを次のセルにコピペして、Markdownに変更して、runして下さい。pythonのコードが「print(a)」と表示されます。

  1.  
  2. ```python
  3. print("a")
  4. ```

　リスト表示を使用するときは以下のように記述します。

  1.  
  2. //Ordered lists:
  3.  
  4. 1. One
  5. 1. Two
  6. 1. Three
  7.  
  8. ---
  9.  
  10. //Unordered lists:
  11.  
  12. * One
  13. * Two
  14. * Three
  15.  

　数式を表示するときは以下のような様式を採用します。HTMLでのLaTex形式とほとんど同一です。以下のコードを次のセルにコピペして同様にrunして下さい。綺麗な数式が表示されたでしょう。

  1.  
  2. //Equations:
  3.  
  4. $y=x^2$
  5.  
  6. $e^{i\pi} + 1 = 0$
  7.  
  8. $e^x=\sum_{i=0}^\infty \frac{1}{i!}x^i$
  9.  
  10. $\frac{n!}{k!(n-k)!} = {n \choose k}$
  11.  
  12. $A_{m,n} =
  13. \begin{pmatrix}
  14. a_{1,1} & a_{1,2} & \cdots & a_{1,n} \\
  15. a_{2,1} & a_{2,2} & \cdots & a_{2,n} \\
  16. \vdots & \vdots & \ddots & \vdots \\
  17. a_{m,1} & a_{m,2} & \cdots & a_{m,n}
  18. \end{pmatrix}$
  19.  

　以下は表を表示するときの記述様式です。

  1.  
  2. //Tables:
  3.  
  4. First column name | Second column name
  5. -------------------|------------------
  6. Row 1, Col 1 | Row 1, Col 2
  7. Row 2, Col 1 | Row 2, Col 2
  8.  
  9. //Horizontal rules:
  10.  
  11. ---
  12.  

　このコードも前と同じように実行して下さい。最後の行は水平線を引く記述です。

　Google Colabでは、Markdownの記法として、Jupyter Notebookのように(MathJax）LaTex表現をサポートしていますが、HTMLタグを許可していません。また、Colabは、絵文字やToDoチェックボックスなどのGitHubの追加をサポートしていません。

　Markdownの公式サイトでの表現形式の説明は以下のサイトにあります。


このページの先頭に戻る

Python Tutorials に行く