LoginSignup
80
89

More than 5 years have passed since last update.

@cha2maru(cha2maru withoutcane)

Atom Markdown Preview Enhancedで業務に関する全てのドキュメントを書くためのTips

Last updated at Posted at 2016-09-30

はじめに

こちらの投稿で紹介しているMarkdown Preview Enhanced、激しく便利に使い倒しています。
現在の業務で使っているドキュメントは出来る限りこれで書くことにしており、チーム内での布教活動も実施して徐々にファンも増えていってる状況です。
この投稿ではそんな俺が業務でMarkdown Preview Enhancedを使っていて便利なTipsをまとめていきます。
Markdown Preview Enhancedに特化していない内容も多いですがご容赦ください

最初に見るべきもの

これまでは最新の更新はCHANGELOG.mdに記載されていましたが、0.12.6 releaseより
NEWEST.mdに記載されているようです。
更新内容も多いので注意してみてください。

唐突に結論

mumeに以降したり階層構造が微妙に変わったりと色々かわっているため、現時点での最新の設定を以下に記載します。
以下の設定をすることで

  • 章節番号の付与（スライド時には付与しない）
  • テーブルセル内の左寄せ、文字レベルの改行
  • Mermaid.jsのガントチャートの日付表示の変更

が行われます
設定内容に関する解説、設定方法については本文参照。

style.less
.markdown-preview.markdown-preview {
  font-family: "Lucida Grande", Meiryo, sans-serif;
  h1 {
    counter-reset: h2counter;
  }
  h2 {
    counter-increment: h2counter;
    counter-reset: h3counter;
  }
  h3 {
    counter-increment: h3counter;
    counter-reset: h4counter;
  }
  h4 {
    counter-increment: h4counter;
  }
  h2:before {
    content: counter(h2counter) ". ";
  }
  h3:before {
    content: counter(h2counter) ". " counter(h3counter) ". ";
  }
  h4:before {
    content: counter(h2counter) ". " counter(h3counter) ". " counter(h4counter)
      ". ";
  }
  table {
    width: 90%;
  }
  th,
  td {
    word-break: break-all;
  }

  @media print {
    font-family: "Lucida Grande", Meiryo, sans-serif;
  }
  // custom prince pdf export style
  &.prince {
  }
  // custom phantomjs png/jpeg export style
  &.phantomjs-image {
  }
  //custom phantomjs pdf export style
  &.phantomjs-pdf {
  }
  // custom presentation style
  .reveal .slides {
    // modify all slides
    p,
    ol,
    li,
    h1,
    h2,
    h3,
    h4,
    h5,
    h6 {
      text-transform: none;
      text-align: left;
    }
    h2:before,
    h3:before,
    h4:before,
    h5:before,
    h6:before {
      content: "";
    }
  }
  .slides > section:nth-child(1) {
    // this will modify `the first slide`
  }
}

.md-sidebar-toc.md-sidebar-toc {
  // sidebar TOC style
}
mermaid_config.js
// config mermaid init call
// http://knsv.github.io/mermaid/#configuration
//
// You can edit the 'MERMAID_CONFIG' variable below.
MERMAID_CONFIG = {
  startOnLoad: false,
  gantt: {
    fontSize: 11,
    axisFormatter: [
      // Within a day
      ["X%I:%M", function (d) {
        return d.getHours();
      }],
      // Monday a week
      ["%m/%d", function (d) {
        return d.getDay() == 1;
      }],
      // Day within a week (not monday)
      ["%m/%d", function (d) {
        return d.getDay() && d.getDate() != 1;
      }],
      // within a month
      ["%m/%d", function (d) {
        return d.getDate() != 1;
      }],
      // Month
      ["%y-%m", function (d) {
        return d.getMonth();
      }]
    ]
  }
}

気にするべき更新点

Version 0.14.2

cssによるカスタマイズ機能がリセットされています。
というか更新時にまっさらにされましたorz
そのうえスライドショーのコンフィグ方法も変わってます。

Version 0.12.6

import機能が大幅に更新されています。

  • import形式のオプション設定が可能
    • 画像の場合はサイズとか
    • コードブロックやコードチャンクに直接インポートとか
  • 外部URLのimportが可能

特にコードブロックとかは、直接作ったものをファイルとしてもってきて検討資料につっこんだりするのに便利そうです！

Version 0.9.6

import記法が追加されています。

これに伴いmermaid等の表記方法が（また）更新されています。
旧

{mermaid}

新

@mermaid

旧来の{}囲みの記法はのきなみコードチャンク扱いになるのでご注意ください。

章節番号をつける

業務上のドキュメントでは章節番号をつけなきゃいけないことが多いので、CSSを修正します。

Ctrl+Shift+Pを押した上で"Markdown Preview Enhance: Customize Css"を選択することで、Preview時のCSSを修正することができます。
そうして開かれたstyles.lessファイルを以下のように修正します。

styles.less
.markdown-preview-enhanced-custom {
    // please write your custom style here
    // eg:
    //  color: blue;          // change font color
    //  font-size: 14px;      // change font size
    //
    // custom pdf output style
    h1 {
        counter-reset: h2counter;
    }
    h2 {
        counter-increment: h2counter;
        counter-reset: h3counter;
    }
    h3 {
        counter-increment: h3counter;
        counter-reset: h4counter;
    }
    h4 {
        counter-increment: h4counter;
    }
    h2:before {
        content: counter(h2counter) ". ";
    }
    h3:before {
        content: counter(h2counter) ". " counter(h3counter) ". ";
    }
    h4:before {
        content: counter(h2counter) ". " counter(h3counter) ". " counter(h4counter) ". ";
    }
    @media print {}
}

これにより、h2からh4までの見出しには章節項の番号がつくようになります。
h1はタイトル利用が多いのでつけないようにしています。

スライドのときには章節番号をつけない

上記の設定を行ってしまうと、Reveal.jsを利用したスライド時に妙な形で番号がついてしまいます。
これでは使いづらいため、以下の設定をすることでスライド表示時は番号をつけないようにできます。
編集対象は同じくstyle.lessです

styles.less

    // custom presentation style
     &[data-presentation-mode],
    .preview-slides .slide {
        // eg
        // background-color: #000;
        h2:before {
            content: "" !important;
        }
        h3:before {
            content: "" !important;
        }
        h4:before {
            content: "" !important;
        }
        h5:before {
            content: "" !important;
        }
        h6:before {
            content: "" !important;
        }
    }

もうちょっとスマートにできたらいいのですが、今はこんな感じで無理やり消してます。

Mermaid.jsのガントチャートで日付表示を調整する

Markdown Preview EnhancedではMermaid.jsを使った図のレンダリングができます。
アクティビティ図やシーケンス図はPlantUMLの方がメジャーなのでそちらを使っているのですが、ガントチャートがレンダリングできるのはMermaid.jsだけなので、そちらで書くようにしています。
（むしろこれがはいっているからMarkdown Preview Enhancedを選んだまである）

ただし、Mermaid.jsのガントチャートは週単位のプロット時に、日付のところが「１月第一週をw.1として、何週目か」を表示してたりします。
少なくともこれだとかなりわかりづらいのでそこを修正します。

Ctrl+Shift+Pを押した上で"Markdown Preview Enhance: Config Mermaid"を選択することで、Preview時にMermaid.jsを呼び出す際の引数を修正することができます。
（実際にどんな引数かはここ参照）
そうして呼び出されたconfig_mermaid.jsを以下のように修正します。

config_mermaid.js
'use strict'
// config mermaid init call
// http://knsv.github.io/mermaid/#configuration
//
// you can edit the 'config' variable below
// everytime you changed this file, you may need to restart atom.
let config = {
    startOnLoad: false,
    gantt: {
        fontSize: 11,
        axisFormatter: [
            // Within a day
            ["X%I:%M", function(d) {
                return d.getHours();
            }],
            // Monday a week
            ["%m/%d", function(d) {
                return d.getDay() == 1;
            }],
            // Day within a week (not monday)
            ["%m/%d", function(d) {
                return d.getDay() && d.getDate() != 1;
            }],
            // within a month
            ["%m/%d", function(d) {
                return d.getDate() != 1;
            }],
            // Month
            ["%y-%m", function(d) {
                return d.getMonth();
            }]
        ]
    }
}

module.exports = config || {
    startOnLoad: false
}

上記のconfig.gantt.axisFormatterが日付の設定であり、それぞれ月とか一日内とかの表示を修正することができます。基本的にはここを参考にしつつ、"%m/%d"とかを修正すれば以下ようにもできるはずです。

Wordでの出力

出力方法

Markdownでドキュメントを書いて、HTMLで納品しようとしたら「Word形式で欲しいな」と言われることがあります。その場合はPandocを用いた出力機能を用いて出力しましょう。

出力の際にはまずはFrontmatterを設定する必要があります。
Markdownファイルの行頭に以下のような設定をしましょう。

---
title: "markdown"
author: "cha2maru"
date: 2016/12/07
output: word_document
---

上記のoutput欄ではドキュメントの形式を指定します。その他出力形式も対応できるため、詳しくはPandocのドキュメントを参照してください。

上記を記述したうえで、Markdown Preview Enhancedのプレビュー画面を右クリック、メニューからPandocを選択することでWordファイルを出力することができます。

スタイルの設定

Pandocを用いたWordファイル出力では事前にスタイルを定義したドキュメントを利用することで、適切なスタイルを適用することができます。

Web上での解説では

pandoc --print-default-data-file reference.docx > reference.docx

を実行してreference.docxを作成し、編集しろと記載されていることが多いですが、Windows7環境PandocV1.19ではなぜかわからないのですが上記ファイルがOffice365で開くことができません。（ファイルが破損していると言われる。）

ただ、reference.docxはWord独自のテンプレートファイルというわけではなく、期待されているスタイルが定義された普通のドキュメントファイルであるため、上記を気にすることなく、先の節で出力したWordファイルに対してスタイルを適用することで、利用することができます。
なので、まずは出力されたWordファイルについて（スタイルの名称を変えることなく）書式を設定してください。

スタイルの適用

Pandocにおける上記のreference.docxを用いたスタイルの適用は

  • コマンドラインで--reference-docx=reference.docxを指定する。
  • Default User Data Folder（pandoc -v で表示される）に格納する。

の二通りがありますが、Markdown Preview Enhancedで利用する場合には後者を利用してください。

（reference-docxはfrontmatterでは指定できないというissueがあった。間違いであればコメントお願いします。）

テーブルの書式設定ができない

何故かわかりませんが、上記方法のように適当なファイルでスタイルを適用する際に、テーブルに関する書式設定をするとファイルが破損された扱いになったりします。
Wordの復旧機能に任せるとちゃんと読めますが、テーブルの書式は消えます。なんでや・・・

おわりに

Markdown Preview Enhancedは今も開発が精力的に行われているため、知らないうちに便利な機能が増えている可能性があるため、油断できなくてかなり助かってますｗ
個人的にはMarkdown Preview EnhancedのExport機能だけがCommandLine上で動くものがNPMに公開されてくれれば最高にハッピーになれるんじゃないかなとも思っていますが、誰かつくってくれないかな・・・（Gitbookはなんか違ったんですよね。。。）

以上です。

80
89
4

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
80
89