VuePress:Markdownを設定変更やプラグイン追加によってカスタマイズする方法

Tips

VuePress:Markdownを設定変更やプラグイン追加によってカスタマイズする方法

VuePressのMarkdown設定を変更して、自分好みに使いやすくするカスタマイズ方法をいくつか紹介します。
また、デフォルトでは用意されていない機能(記述方法)を、プラグインを追加して使用可能にする方法も併せて紹介します。

※VuePressの基本的な使い方については「VuePress入門」で紹介しているので、そちらを参照してください。

※ここで紹介している内容は、VuePress Ver 0.14.8 を使用し、すべて/.vuepress内のconfig.jsに記述していく想定になります。
Ver 1.x 系でも基本的に動くとは思いますが、markdown.configなど一部バージョンによって記述が変わっている箇所もあるので、何か問題があった場合は公式リファレンスなどを参照してください。

VuePress:Markdownを設定変更やプラグイン追加によってカスタマイズする方法 目次

  1. コードブロックに行番号を表示
  2. アンカーの無効化
  3. アンカーシンボルの変更
  4. 外部リンクの属性・属性値を変更
  5. URL記述を自動的にリンク設定する
  6. 目次の対象となる見出しレベルを調整
  7. プラグイン:略語・頭字語対応
  8. プラグイン:脚注対応
  9. プラグイン:ハイライト表示対応
  10. プラグイン:CodePenとJSFiddleの埋め込み対応
  11. プラグイン:YouTubeとVimeoの埋め込み対応
  12. プラグイン:タスクリスト対応
  13. プラグイン:Font Awesome対応

1. コードブロックに行番号を表示

コードブロックに行番号を表示

markdown.lineNumbertrueにすることでコードブロックに行番号を表示させることができます。

config.js

module.exports = {
  markdown: {
    lineNumbers: true
  }
}

目次へ

2. アンカーの無効化

デフォルトでは#######で記述された見出しにホバーするとテキスト横に「#」が表示されて、クリックでハッシュがURLに反映される動きになっていますが、markdown.anchorで下記のように記述することでその動きを無効化でき、見出しをホバーしても「#」が表示されなくなります。

config.js

module.exports = {
  markdown: {
    anchor: {
      permalink: false
    }
  }
}

目次へ

3. アンカーシンボルの変更

デフォルトでは#######で記述された見出しにホバーするとテキスト横に「#」が表示されますが、それを同じくmarkdown.anchorで下記のように記述することで任意のシンボルに変更できます。
このサンプルコードの場合は「#」が「?」になります。

config.js

module.exports = {
  markdown: {
    anchor: {
      permalinkSymbol: '?'
    }
  }
}

目次へ

4. 外部リンクの属性・属性値を変更

デフォルトでは外部リンクに対してtarget="_blank"rel="noopener noreferrer"が付与されるのですが、これらはmarkdown.externalLinksで変更することができます。
例えばtarget="_blank"を無効化したい場合は下記のように記述します。

config.js

module.exports = {
  markdown: {
    externalLinks: {
      target: ''
    }
  }
}

また、新しく属性を追加することもでき、下記の場合はtarget="_blank"を無効化にしつつ.linkというclassが付与されるようになります。

config.js

module.exports = {
  markdown: {
    externalLinks: {
      target: '',
      class: 'link'
    }
  }
}

目次へ

5. URL記述を自動的にリンク設定する

デフォルトではリンク指定されたURLを表示させたい場合は、[URL](URL)のように記述する必要がありますが、下記のように記述することでURLを記述するだけでリンク設定されるようになります。

config.js

module.exports = {
  markdown: {
    linkify: true
  }
}

目次へ

6. 目次の対象となる見出しレベルを調整

[[toc]]で目次を表示する際、デフォルトでは#####のみが対象になりますが、markdown.tocで下記のように記述することで対象となる見出しレベルを調整することができます。
このサンプルコードの場合は########までを対象にしたものになります。

config.js

module.exports = {
  markdown: {
    toc: {
      includeLevel: [2, 3, 4, 5, 6]
    }
  }
}

目次へ

7. プラグイン:略語・頭字語対応

略語・頭字語対応

略語や頭字語であることを表す際に使用するabbr要素をMarkdownで使えるようにします。
実装には「markdown-it-abbr」を使用するので下記コマンドでインストール後、config.jsに読み込みの記述をします。

$ yarn add -D markdown-it-abbr

config.js

module.exports = {
  markdown: {
    config: md => {
      md.use(require('markdown-it-abbr'))
    }
  }
}

使用する際は下記のような形で記述し、この場合は「HTML」と「W3C」が<abbr>で括られ、ホバーすると説明が表示されるようになります。

example.md

*[HTML]: Hyper Text Markup Language
*[W3C]:  World Wide Web Consortium
The HTML specification is maintained by the W3C.

上のイメージのように装飾した形で表示したい場合は、下記のようなスタイルで実装できます。

/.vuepress/style.styl

abbr {
  position: relative;
  &::after {
    content: attr(title);
    position: absolute;
    bottom: 100%;
    left: 50%;
    display: inline-block;
    min-width: 200px;
    padding: .6em .8em;
    background: #3eaf7c;
    border-radius: 4px;
    color: #fff;
    font-size: 14px;
    line-height: 1.4;
    transform: translateX(-50%);
    transition: .2s;
    opacity: 0;
    visibility: hidden;
  }
  &:hover::after {
    bottom: 120%;
    opacity: 1;
    visibility: visible;
  }
}

目次へ

8. プラグイン:脚注対応

脚注対応

ブログでたまに見る脚注の見栄え・動きをMarkdownで使えるようにします。
実装には「markdown-it-footnote」を使用するので下記コマンドでインストール後、config.jsに読み込みの記述をします。

$ yarn add -D markdown-it-footnote

config.js

module.exports = {
  markdown: {
    config: md => {
      md.use(require('markdown-it-footnote'))
    }
  }
}

使用する際は下記のような形で脚注を設定したい箇所に[^n]を記述し、その後[^n]:を先頭に付けて脚注として表示したい内容を入力します。
問題なければ上のイメージのように文章内にリンク設定付きの[1][2]といった脚注番号が表示され、ページ下部に内容が表示されるようになります。

example.md

あのイーハトーヴォ[^1]のすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市[^2]、郊外のぎらぎらひかる草の波。
[^1]: これは1つ目の脚注です。
[^2]: これは2つ目の脚注です。

目次へ

9. プラグイン:ハイライト表示対応

ハイライト表示対応

指定箇所がmark要素で括られ、ハイライト表示させることができるようにします。
実装には「markdown-it-mark」を使用するので下記コマンドでインストール後、config.jsに読み込みの記述をします。

$ yarn add -D markdown-it-mark

config.js

module.exports = {
  markdown: {
    config: md => {
      md.use(require('markdown-it-mark'))
    }
  }
}

使用する際は下記のような形で適用させたい前後に==を記述します。
デフォルトでは背景が黄色ですが、markに対してbackground-colorcolorのスタイルを指定すれば任意の見栄えにできます。

example.md

文章内の一部を==このようにハイライト表示==させることができます。

目次へ

10. プラグイン:CodePenとJSFiddleの埋め込み対応

CodePenとJSFiddleの埋め込みを容易にできるようにします。
実装には「markdown-it-playground」を使用するので下記コマンドでインストール後、config.jsに読み込みの記述をします。

$ yarn add -D markdown-it-playground

config.js

module.exports = {
  markdown: {
    config: md => {
      md.use(require('markdown-it-playground'))
    }
  }
}

使用する際はまずCodePenかJSFiddleかを指定し、その後の()内に各サイトでiframe埋め込みを選択時に表示されるコード内のsrc部分を記述します。

example.md

@[codepen](iframe src)
@[jsfiddle](iframe src)

目次へ

11. プラグイン:YouTubeとVimeoの埋め込み対応

YouTubeとVimeoの埋め込みを容易にできるようにします。
実装には「markdown-it-video」を使用するので下記コマンドでインストール後、config.jsに読み込みの記述をします。

$ yarn add -D markdown-it-video

config.js

module.exports = {
  markdown: {
    config: md => {
      md.use(require('markdown-it-video'))
    }
  }
}

使用する際はまずYouTubeかVimeoかを指定し、その後の()内に表示させたい動画のIDを指定します。
また、動画ID指定だけでなく()内にURLを記述して指定することもできます。

example.md

@[youtube](movie id)
@[vimeo](movie id)

ちなみに、レスポンシブ対応は下記のようなclassやスタイルで可能です。

/.vuepress/style.styl

.embed-responsive {
  position: relative;
  height: 0;
  padding-top: 56.25%;
  overflow: hidden;
  iframe {
    position: absolute;
    top: 0;
    left: 0;
    width: 100%;
    height: 100%;
  }
}

目次へ

12. プラグイン:タスクリスト対応

タスクリスト対応

タスクリスト表示をMarkdownで使えるようにします。
実装には「markdown-it-task-lists」を使用するので下記コマンドでインストール後、config.jsに読み込みの記述をします。

$ yarn add -D markdown-it-task-lists

config.js

module.exports = {
  markdown: {
    config: md => {
      md.use(require('markdown-it-task-lists'))
    }
  }
}

下記のような形で記述すれば上のイメージのようなタスクリストが表示され、[ ]で未チェック、[x]でチェック済みになります。

example.md

- [ ] primary
  - [ ] foo
  - [x] bar
  - [x] baz
- [ ] secondary
- [x] tertiary
- [x] quaternary
- [ ] quinary

タスクリストはul要素でマークアップされているので、場合によってはリストマーカーが表示されます。
これが不要であれば下記のようなスタイルで非表示にできます。

/.vuepress/style.styl

.contains-task-list {
  padding-left: 0;
  list-style: none;
  ul {
    padding-left: 1.2em;
  }
}

目次へ

13. プラグイン:Font Awesome対応

Font Awesome対応

Font AwesomeをMarkdownで使えるようにします。
実装には「markdown-it-task-fontawesome」を使用するので下記コマンドでインストールします。

$ yarn add -D markdown-it-task-fontawesome

インストール後、config.jsにはプラグインの読み込みとhead内でFont AwesomeのCSSを読み込むための記述をします。(integrityの値は各自で変更してください。)

config.js

module.exports = {
  head: [
    ['link', { rel: 'stylesheet', href: 'https://use.fontawesome.com/releases/v5.5.0/css/all.css', integrity: 'xxx', crossorigin: 'anonymous' }]
  ],
  markdown: {
    config: md => {
      md.use(require('markdown-it-task-fontawesome'))
    }
  }
}

使用する際は、下記のようにアイコン名を:で括る形で記述します。

example.md

:fab-vuejs: x :fab-markdown: = VuePress

目次へ


デフォルトでもそこまで不便なく使えますが、このように簡単に設定変更したりプラグインで機能追加できるのは嬉しいですね。
markdown-itは他にもプラグインが沢山ありますし、カスタマイズ次第でいろいろできると思うので、自分にピッタリのMarkdown環境を実装してみてください。

Posted on

Category : Tips

Close the search window,
please press close button or esc key.