2020 5/4 誤字修正
2020 5/5 リンク追加, 構成変更
Jupiter notebookの使い方を解説する記事の第2弾です(第一回はこちら)。今回はJupiter notebookがサポートしているMarkdown記法について説明します。Markdownはプレーンテキストの文書からマークアップ言語であるHTMLを生成するために開発された軽量マークアップ言語です(wiki)。Markdownで書いた文章はパーサを通して構造化された文章として表示されます。HTMLは書きにくいので、これを補うために開発されました。
Markdownを使うと、構造化された文章をコードやバイオインフォのコマンドの間に表示 して、まさにデジタルノートといった使い方ができるようになります。下の写真をみてください。コードの間にMarkdown記法で説明文を書いています。
(写真は例です)
このようにコードの間に構造化された文章を差し込んで見やすいマニュアルを作れます。
Jupiter notebook上でMarkdownに切り替えるには、コマンドモード時にMを押します。
Mを押すと左のIn []が消え、セルがMarkdownモードになります。この状態でEnterを押すとMarkdown記法で記入できます。コードモードに戻すにはYです。
Markdownの書き方を書く前にjupyter notebook以外のMarkdown普及状況について説明します。興味がなければステップ2に行って下さい。
Jupyter Notebook Document - Markdown basics
1、Markdownに対応したエディタ、ブログサイト、ツールなど
普通のエディタでもMarkdownの編集はできますが、リアルタイムプレビュー表示がないとたいへん不便です。そのためMarkdown記法のリアルタイムプレビューに対応したAtomエディタ(プラグインで対応)やマイクロソフトのVS code(link)(関連ツイート)が汎用のMarkdownエディタとして最近はよく使われているようです。さらにMacDownのようなMarkdown専用エディタや(HP)やweb上でMacDownを編集できるStackEdit(HPの一番上にあるstart editingをクリック)などのサイトも複数存在します。また、iOSやAndroid向けのMarkdown対応エディタ、Sphinxなどのmarkdown記法に対応したツールなど色々あります(*2)。拡張機能を入れることで、gmailですらMarkdown技法に対応します(リンク)。
Qiitaやはてなブログの記事はMarkdown記法をサポートしており、見やすい技術系記事を簡単に作成できるようになっています。
Markdownが身近な存在であるよりわかりやすい例は、GithubのREADME.mdです(*1)。README.mdはGithubレポジトリのトップに表示されるDocumentで、プロジェクト新規作成時に自動で生成されます(自動作成のチェックをつけている場合のみ)。このREADME.mdはMarkdown記法で書かれています(*3)(.mdはmarkdownの略)。
1つ既存のレポジトリを見てみましょう。 下に載せた写真はロングリードのアセンブラFlyeレポジトリのトップ画面のキャプチャです。
README.mdはMarkdown記法に従って書かれています。確認のため、FlyeアセンブラのREADMEをMarkdownエディタで開いてみましょう。
まずFlyeのソースコードをダウンロードします。緑のclone or download ボタンからDownload Zipを選択。
zipファイルを解凍して中のREADME.mdをVS code(link)で開いたのが下の写真です。ウィンドウの左半分がMarkdownのコード、右半分がプレビュー表示というレイアウトです。プレビュー表示がwebブラウザでFlyeレポジトリにアクセスした時と同じ体裁になっていることを確認してください。
VS codeでFlye(github)のREADME.mdを開いたところ。macではCommand + K→ VでMarkdownの2画面リアルアイムプレビューモードになる。背景が黒いのはVS codeの仕様。
MacDown(HP)でsomalierというツールのREADME.mdを開いたところ。MacDownではデフォルトで2画面リアルアイムプレビュー表示に対応。
このように、GithubレポジトリではMarkdown記法で書かれたREADME.mdをトップに表示することで、どんなツールやライブラリのレポジトリなのか説明しています。GIhub以外では、例えばDocker HubのDocumentもMarkdown記法で書かれています。
追記
HackMD
軽量かつ共同編集でき、議事録を作成するなどの用途に向いたHackMDというMarkdownエディタもあります。アカウントを作ればすぐ利用開始できます。
・Typora
2画面表示は見にくい場合もあるので、直接MarkdownをスタイリングするTyporaのようなツールもあります(*5)。
Typora — a markdown editor, markdown reader.
こちらのサイトでは色々紹介されています(有料アプリもあります)。
2、Jupiter notebookでMarkdown記法を使う
では早速Jupiter notebook上でMarkdown記法を使ってみましょう。まず 前回と同じディレクトリでJupiter notebookを起動して下さい。
#起動(jupyter notebookでもO.K)
jupyter-notebook
新規ノートを作成します。ノートが立ち上がったら、今回はノート名をmarkdownに変更します(リネームは1回目に説明済み)。
コマンドモードでMを押すとMarkdownモードに変更します。pythonのコードモードに戻すにはYです。
Markdownモードになりました。コードではないため、左のIn [num]は消えています。
Enterを押してセルを編集していきます。
最初に説明したように、markdownモードでは最小限の動作で構造化された文章を出力する事ができます。まず見出しを作成しましょう。見出しは#<スペース>です。#<スペース>の後に文字を打って下さい。
実行前から結果はプレビューされます。
shift + Enterで実行します。見出しなので大きく表示されました。
見出しのサイズは#の数で調整します。#を増やすと小さくなります。htmlの見出しタグ<h>のh1-h6に対応しています。#の後にスペースを入れるのを忘れないで下さい。
実行するとこうなります。
HTMLタグもサポートしています。HTMLタグの<h1> </h1>で書いてみましょう(画像の一番下)。
Markdownで書いたのと同じ結果が出力されました(一番下のセル)。しかし、HTMLタグよりMarkdonw記法の方がずっとシンプルに記述できますね。
コマンドモードにしていったん不要なセルを消しましょう(dd)。
markdownモードかどうかの確認を忘れないでください。markdownモードであれば左端のIn []は無いはずです。
間違ってコードモード(Y)でmarkdown記法の文字を書いてしまった場合、編集モード中にctrl + Mを押して、
コマンドモードに戻します。そのまま
Mを押してmarkdownモードに変え、
再びEnterを押して編集します。
斜体は* *で囲みます。ボールドは** **で囲みます。
実行すると改行が認識されていませんでした。
改行するにはスペースを連続2回打ちます。この例では*斜体*<space><space>です。<space><space>は<br>タグと同じです。
改行されました。
* *で斜体、** ** でボールドでした。*** ***で斜体のボールドになります。
打ち消し線は~~ ~~で囲みます。
出力
*(または+ or -)と<space> or <tab>で箇条書き(リスト)です。箇条書きの時は<space><space>がなくても勝手に改行されます。
出力
数値付きリスト
出力
リンクを張るには[テキスト](URL)、または[テキスト](URL "タイトル")です。
出力
URLをそのまま載せるなら<>で囲みます。
出力
画像は ![代替テキスト](画像のURL)です。
出力
区切り線を引く。*や-を3回以上。
インラインでコードを埋め込む。バッククオートで` `のようにコード部分を混む。
出力
コードのシンタックスハイライト表示。バッククオート3つ(```)と言語名で開始して、最後を```で囲みます。 bashスクリプトならこんな感じで書いて...
出力はこうなります。コードがコマンドや括りごとに見やすく色分けされます(シンタックスハイライトwiki)。もちろんpythonにも対応しています。マニュアルによると数百の言語をサポートしているそうです。
QiitaにはMarkdownの記法をまとめたチートシートが投稿されています。参考にして下さい。
こちらのサイトでは実際に手を動かして学ぶことができます。
長くなってしまったので今回はここまでにします。次は 数式やマジックコマンドについて書いていきます。
引用
Jupyter Notebooks – a publishing format for reproducible computational workflows
Kluyver, Thomas, Ragan-Kelley, Benjamin, Pérez, Fernando, Granger, Brian, Bussonnier, Matthias, Frederic, Jonathan, Kelley, Kyle, Hamrick, Jessica, Grout, Jason, Corlay, Sylvain, Ivanov, Paul, Avila, Damián, Abdalla, Safia, Willing, Carol and Jupyter development team, (2016) Jupyter Notebooks – a publishing format for reproducible computational workflows. Loizides, Fernando and Scmidt, Birgit (eds.)
In Positioning and Power in Academic Publishing: Players, Agents and Agendas. IOS Press. pp. 87-90 . (doi:10.3233/978-1-61499-649-1-87)
参考
*1
*2
*3
GithubのREADME.mdはレポジトリを作成するときに自動で生成され、そのツールでどんなことが行えるのか、そしてどうやって使うのか説明する役割を持っています。詳細はGithubのヘルプを読んで下さい。
*4
HackMDについてはQiitaの記事を読んで下さい。
*5
TyporaについてはこちらのQiita記事を参考にしました。