Markdown
VSCode

Markdown 環境をつくりましょう!(Windows 10, VSC 環境)

More than 1 year has passed since last update.

はじめに

  • 最近、ちょっとしたメモとかを書くときの能率を上げるために、Markdown を使用しています。今までは、txt や docx を使用していましたが、色々な難点が出てきたので、今までは Markdown です。Markdown 記法を覚えることにより、ドキュメント構成の均質化ができるようになりました。
  • Markdown の利点として、
    • Markdown File(.md) を Git でバージョン管理することができる。docx でも Git を利用できますが diff(ファイル差分)が難しいです。Office の標準機能では、Git に連携していないし。WinMerge を使用すればできないこともないですが、エディタ(アプリケーション)で直接見れないので、やりにくい。バージョン管理のトラッキングぐらいにしか使えません。
    • Markdown は使いまわしが楽。例えば、Wordpress などのブログサイトでも使います事が可能です(ただし、方言があるので一部変える必要があることがある)

環境

  • エディタとしては、マイクロソフトの Visual Studio Code(VSC) を使用します。
    • https://code.visualstudio.com/download
    • Windows, Mac, Linux と多様なプラットフォームで実行できるエディタです。更新が多いのが気になりますが、使いやすいです。嫌なら、Atom とか使えばいいと思います。
  • この記事は、Windows 10 環境で行います。Mac と Linux はパスとか変えてください。

ゴール(目標)

  • Markdown(.md) を pdf に変換できるようにしましょう。pdf なら報告書、レポートでも優秀だし。後述しますが、Markdown PDF の初期設定では、フォントなどが弱いため、CSS を組み込みます。

最初に

  • VSC をインストールします。

VSC で最初にやること

VSC の設定(setting.json)

  • VSC のユーザ設定(setting.json)を変更(追記します)
#VSC の基本的な部分です(フォントサイズと VSC で表示するフォントを指定します。
 "editor.fontSize" : 14,
 "editor.fontFamily": ["Ricty Diminished"],
  • Markdown PDF の設定
    • VSC のユーザ設定(setting.json)を変更(追記します)
//Markdown to pdf の設定用です
//Markdown to Pdf のフォントはCSS で呼ばないと、pdf に反映できない。
    "markdown-pdf.convertOnSave": false,
    "markdown-pdf.styles": [
        "C:\\Users\\(User accountの名前)\\.vscode\\markdown.css"
    ],
//Markdown to Pdf の印刷レイアウトです。
    "markdown-pdf.format": "A4",
// ページオプション。 portrait(縦向き)、landscape(横向き)
    "markdown-pdf.orientation": "portrait",
// ページオプション。 上ボーダー. 単位: mm, cm, in, px
    "markdown-pdf.border.top": "1.5cm",

// ページオプション。下ボーター. 単位: mm, cm, in, px
    "markdown-pdf.border.bottom": "1cm",

// ページオプション。 右ボーダー. 単位: mm, cm, in, px
    "markdown-pdf.border.right": "1cm",

// ページオプション。 左ボーダー. 単位: mm, cm, in, px
    "markdown-pdf.border.left": "1cm",

// ヘッダー コンテンツ
    "markdown-pdf.header.contents": "",
  • フォントの指定ができない。また、小節立てを(1., 1.1., 1.1.1.,)とさせたいので CSS を用意します。CSS の保存先は、先述した <"C:\Users\(User accountの名前)\.vscode\markdown.css"> に保存します。
body{
    font-family: "游ゴシック";
    font-size: 10.5pt;
    counter-reset: chapter;
}

code, code span{
    font-family: "Ricty Diminished";
}

h1 {
    counter-reset: sub-chapter;
}
h2 {
    counter-reset: section;
}
h1::before {
    counter-increment: chapter;
    content: counter(chapter) ". ";
}
h2::before {
    counter-increment: sub-chapter;
    content: counter(chapter) "." counter(sub-chapter) ". ";
}
h3::before {
    counter-increment: section;
    content: counter(chapter) "." counter(sub-chapter) "." counter(section) ". ";
}
  • Markdown プレビューの設定。
    • このままだと、ドキュメントを作るたびに pdf を作成するため、能率的ではありません。VSC のプレビュー機能を使用します。
    • Markdown PDF と同じ CSS を読めるように settings.json を追記します。
    • これを適用することで、デフォルトのプレビューのフォントから開放されます!
 "markdown.styles": [
        "C:\\Users\\(User accountの名前)\\.vscode\\markdown.css"
    ],

まとめ

  • Windows での Markdown 環境の設定手順を記述しました。ソースコードは Markdown になり、ドキュメントは pdf になります。ソースコードの管理は、Git を使用しましょう!バージョン管理が楽です。
  • Pandoc を使用するという方法があるようですが、VSC + Markdown PDF なら pdf の変換もエディタ上でできます。Pandoc で使用していた CSS も使いまわせる?はず

    • Pandoc でできて VSC でできることで、図表番号の参照があります・・・
  • 私はナレッジ管理を、pukiwiki で行っていますが、(Markdown → pukiwiki に変換)という Ruby スクリプトで行っています。

  • 学生は Latex の代わり、エンジニアはエクセル方眼紙、docx の代わりにと使用できかと思います。。

  • Markdown 記法の書き方は、チートシートを作っている人がいます。

参考