macでインフォマティクス

macでインフォマティクス

HTS (NGS) 関連のインフォマティクス情報についてまとめています。

Jupiter notebookの使い方其の2(Markdown記法について)

2020 5/4 誤字修正

2020 5/5  リンク追加, 構成変更

 

 Jupiter notebookの使い方を解説する記事の第2弾です(第一回はこちら)。今回はJupiter notebookがサポートしているMarkdown記法について説明します。Markdownはプレーンテキストの文書からマークアップ言語であるHTMLを生成するために開発された軽量マークアップ言語です(wiki)。Markdownで書いた文章はパーサを通して構造化された文章として表示されます。HTMLは書きにくいので、これを補うために開発されました。

 Markdownを使うと、構造化された文章をコードやバイオインフォのコマンドの間に表示 して、まさにデジタルノートといった使い方ができるようになります。下の写真をみてください。コードの間にMarkdown記法で説明文を書いています。

f:id:kazumaxneo:20200503181500p:plain

(写真は例です)

このようにコードの間に構造化された文章を差し込んで見やすいマニュアルを作れます。

 

Jupiter notebook上でMarkdownに切り替えるには、コマンドモード時にMを押します。

f:id:kazumaxneo:20200503223515p:plain

Mを押すと左のIn []が消え、セルがMarkdownモードになります。この状態でEnterを押すとMarkdown記法で記入できます。コードモードに戻すにはYです。

 

Markdownの書き方を書く前にjupyter notebook以外のMarkdown普及状況について説明します。興味がなければステップ2に行って下さい。

 

Jupyter Notebook Document - Markdown basics

 

1、Markdownに対応したエディタ、ブログサイト、ツールなど

 普通のエディタでもMarkdownの編集はできますが、リアルタイムプレビュー表示がないとたいへん不便です。そのためMarkdown記法のリアルタイムプレビューに対応したAtomエディタ(プラグインで対応)やマイクロソフトVS codelink)(関連ツイート)が汎用のMarkdownエディタとして最近はよく使われているようです。さらにMacDownのようなMarkdown専用エディタや(HP)やweb上でMacDownを編集できるStackEdit(HPの一番上にあるstart editingをクリック)などのサイトも複数存在します。また、iOSAndroid向けのMarkdown対応エディタ、Sphinxなどのmarkdown記法に対応したツールなど色々あります(*2)。拡張機能を入れることで、gmailですらMarkdown技法に対応します(リンク)。

 Qiitaやはてなブログの記事はMarkdown記法をサポートしており、見やすい技術系記事を簡単に作成できるようになっています。

f:id:kazumaxneo:20200503185444p:plain

はてなブログではMarkdown記法で記事を作成できる。

 

 Markdownが身近な存在であるよりわかりやすい例は、GithubREADME.mdです(*1)。README.mdはGithubレポジトリのトップに表示されるDocumentで、プロジェクト新規作成時に自動で生成されます(自動作成のチェックをつけている場合のみ)。このREADME.mdはMarkdown記法で書かれています(*3)(.mdはmarkdownの略)。

 1つ既存のレポジトリを見てみましょう。 下に載せた写真はロングリードのアセンブラFlyeレポジトリのトップ画面のキャプチャです。

f:id:kazumaxneo:20200503163949p:plain

 

README.mdはMarkdown記法に従って書かれています。確認のため、FlyeアセンブラのREADMEをMarkdownエディタで開いてみましょう。

 

まずFlyeのソースコードをダウンロードします。緑のclone or download ボタンからDownload Zipを選択。

f:id:kazumaxneo:20200503171457p:plain

 

zipファイルを解凍して中のREADME.mdをVS codelink)で開いたのが下の写真です。ウィンドウの左半分がMarkdownのコード、右半分がプレビュー表示というレイアウトです。プレビュー表示がwebブラウザでFlyeレポジトリにアクセスした時と同じ体裁になっていることを確認してください。

f:id:kazumaxneo:20200503121615p:plain

VS codeでFlye(github)のREADME.mdを開いたところ。macではCommand + KVMarkdownの2画面リアルアイムプレビューモードになる。背景が黒いのはVS codeの仕様。

 

f:id:kazumaxneo:20200503165920p:plain

MacDown(HP)でsomalierというツールのREADME.mdを開いたところ。MacDownではデフォルトで2画面リアルアイムプレビュー表示に対応。

 

このように、GithubレポジトリではMarkdown記法で書かれたREADME.mdをトップに表示することで、どんなツールやライブラリのレポジトリなのか説明しています。GIhub以外では、例えばDocker HubのDocumentもMarkdown記法で書かれています。 

f:id:kazumaxneo:20200504005826p:plain

 

追記

HackMD

軽量かつ共同編集でき、議事録を作成するなどの用途に向いたHackMDというMarkdownエディタもあります。アカウントを作ればすぐ利用開始できます。

f:id:kazumaxneo:20200504233832p:plain

 

 

・Typora

2画面表示は見にくい場合もあるので、直接MarkdownをスタイリングするTyporaのようなツールもあります(*5)。

Typora — a markdown editor, markdown reader.

f:id:kazumaxneo:20200504190755p:plain

 

こちらのサイトでは色々紹介されています(有料アプリもあります)。

 

 

2、Jupiter notebookでMarkdown記法を使う

では早速Jupiter notebook上でMarkdown記法を使ってみましょう。まず 前回と同じディレクトリでJupiter notebookを起動して下さい。

#起動(jupyter notebookでもO.K)
jupyter-notebook

  

新規ノートを作成します。ノートが立ち上がったら、今回はノート名をmarkdownに変更します(リネームは1回目に説明済み)。

f:id:kazumaxneo:20200503222833p:plain

 

コマンドモードでMを押すとMarkdownモードに変更します。pythonのコードモードに戻すにはYです。

f:id:kazumaxneo:20200503223459p:plain

 

Markdownモードになりました。コードではないため、左のIn [num]は消えています。

f:id:kazumaxneo:20200503223515p:plain

 

Enterを押してセルを編集していきます。

f:id:kazumaxneo:20200503223720p:plain

 

最初に説明したように、markdownモードでは最小限の動作で構造化された文章を出力する事ができます。まず見出しを作成しましょう。見出しは#<スペース>です。#<スペース>の後に文字を打って下さい。

f:id:kazumaxneo:20200503225908p:plain

実行前から結果はプレビューされます。

 

shift + Enterで実行します。見出しなので大きく表示されました。

f:id:kazumaxneo:20200503225842p:plain

 

見出しのサイズは#の数で調整します。#を増やすと小さくなります。htmlの見出しタグ<h>のh1-h6に対応しています。#の後にスペースを入れるのを忘れないで下さい。

f:id:kazumaxneo:20200503230403p:plain
 

実行するとこうなります。

f:id:kazumaxneo:20200503230421p:plain


HTMLタグもサポートしています。HTMLタグの<h1> </h1>で書いてみましょう(画像の一番下)。

f:id:kazumaxneo:20200503230906p:plain

 

Markdownで書いたのと同じ結果が出力されました(一番下のセル)。しかし、HTMLタグよりMarkdonw記法の方がずっとシンプルに記述できますね。

f:id:kazumaxneo:20200503231001p:plain

 

コマンドモードにしていったん不要なセルを消しましょう(dd)。

f:id:kazumaxneo:20200503231147p:plain

 

markdownモードかどうかの確認を忘れないでください。markdownモードであれば左端のIn []は無いはずです。

f:id:kazumaxneo:20200503223515p:plain

 

間違ってコードモード(Y)でmarkdown記法の文字を書いてしまった場合、編集モード中にctrl + Mを押して、

f:id:kazumaxneo:20200503231609p:plain

コマンドモードに戻します。そのまま

f:id:kazumaxneo:20200503231855p:plain

Mを押してmarkdownモードに変え、

f:id:kazumaxneo:20200503231912p:plain

再びEnterを押して編集します。

f:id:kazumaxneo:20200503232020p:plain

 

斜体は* *で囲みます。ボールドは** **で囲みます。

f:id:kazumaxneo:20200503232550p:plain

 

実行すると改行が認識されていませんでした。

f:id:kazumaxneo:20200503232842p:plain


改行するにはスペースを連続2回打ちます。この例では*斜体*<space><space>です。<space><space>は<br>タグと同じです。

f:id:kazumaxneo:20200503233213p:plain

改行されました。

 

* *で斜体、** ** でボールドでした。*** ***で斜体のボールドになります。

f:id:kazumaxneo:20200504120554p:plain

 

打ち消し線は~~ ~~で囲みます。

f:id:kazumaxneo:20200504115923p:plain

出力

f:id:kazumaxneo:20200504120203p:plain

 

 *(または+ or -)と<space> or <tab>で箇条書き(リスト)です。箇条書きの時は<space><space>がなくても勝手に改行されます。

f:id:kazumaxneo:20200504010319p:plain

出力

f:id:kazumaxneo:20200504010457p:plain

 

数値付きリスト

f:id:kazumaxneo:20200504011237p:plain

出力

f:id:kazumaxneo:20200504011239p:plain

 

リンクを張るには[テキスト](URL)、または[テキスト](URL "タイトル")です。

f:id:kazumaxneo:20200504011656p:plain

出力

f:id:kazumaxneo:20200504011717p:plain

 

URLをそのまま載せるなら<>で囲みます。

f:id:kazumaxneo:20200504120821p:plain

出力

f:id:kazumaxneo:20200504120853p:plain

 

画像は ![代替テキスト](画像のURL)です。

f:id:kazumaxneo:20200504012221p:plain

出力

f:id:kazumaxneo:20200504012141p:plain

 

区切り線を引く。*-を3回以上。

f:id:kazumaxneo:20200504012658p:plain

 

インラインでコードを埋め込む。バッククオートで` `のようにコード部分を混む。

f:id:kazumaxneo:20200504161047p:plain

 出力

f:id:kazumaxneo:20200504161050p:plain

 

コードのシンタックスハイライト表示。バッククオート3つ(```)と言語名で開始して、最後を```で囲みます。 bashスクリプトならこんな感じで書いて...

f:id:kazumaxneo:20200504121920p:plain

 

出力はこうなります。コードがコマンドや括りごとに見やすく色分けされます(シンタックスハイライトwiki)。もちろんpythonにも対応しています。マニュアルによると数百の言語をサポートしているそうです。

f:id:kazumaxneo:20200504122157p:plain

 

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記事を参考にしました。