VuePressのMarkdownを自分好みに使いやすくするカスタマイズ方法をいくつか紹介します。
また、デフォルトでは用意されていない機能(記述方法)をプラグインを追加して使用可能にする方法も併せて紹介します。
- VuePressの基本的な使い方については「VuePress入門」で紹介しているのを参考にしてください。
- 紹介している内容は、VuePress Ver 0.14.8を使用し、すべて
/.vuepress
内のconfig.js
に記述していく想定になります。
Ver 1.x系でも基本的に動くとは思いますが、markdown.config
など一部バージョンによって記述が変わっている箇所もあるので、何か問題があった場合は公式リファレンスなどを参照してください。
コードブロックに行番号を表示
markdown.lineNumber
をtrue
にすることでコードブロックに行番号を表示させることができます。
module.exports = {
markdown: {
lineNumbers: true
}
}
アンカーの無効化
デフォルトでは#
〜######
で記述された見出しにホバーするとテキスト横に「#」が表示されて、クリックでハッシュがURLに反映される動きになっていますが、markdown.anchor
で下記のように記述することでその動きを無効化でき、見出しをホバーしても「#」が表示されなくなります。
module.exports = {
markdown: {
anchor: {
permalink: false
}
}
}
アンカーシンボルの変更
デフォルトでは#
〜######
で記述された見出しにホバーするとテキスト横に「#」が表示されますが、markdown.anchor
で下記のように記述することで任意のシンボルに変更できます。
このサンプルコードの場合は「#」が「?」になります。
module.exports = {
markdown: {
anchor: {
permalinkSymbol: '?'
}
}
}
外部リンクの属性・属性値を変更
デフォルトでは外部リンクに対してtarget="_blank"
とrel="noopener noreferrer"
が付与されるのですが、これらはmarkdown.externalLinks
で変更することができます。
例えばtarget="_blank"
を無効化したい場合は下記のように記述します。
module.exports = {
markdown: {
externalLinks: {
target: ''
}
}
}
また、新しく属性を追加することもでき、下記の場合はtarget="_blank"
を無効化にしつつ.link
というclassが付与されるようになります。
module.exports = {
markdown: {
externalLinks: {
target: '',
class: 'link'
}
}
}
URL記述を自動的にリンク設定する
デフォルトではリンク指定されたURLを表示させたい場合は、[URL](URL)
のように記述する必要がありますが、下記のように記述することでURLを記述するだけでリンク設定されるようになります。
module.exports = {
markdown: {
linkify: true
}
}
目次の対象となる見出しレベルを調整
[[toc]]
で目次を表示する際、デフォルトでは##
と###
のみが対象になりますが、markdown.toc
で下記のように記述することで対象となる見出しレベルを調整することができます。
このサンプルコードの場合は##
〜######
までを対象にしたものになります。
module.exports = {
markdown: {
toc: {
includeLevel: [2, 3, 4, 5, 6]
}
}
}
プラグイン:略語・頭字語対応
略語や頭字語であることを表す際に使用するabbr
要素をMarkdownで使えるようにします。
実装には「markdown-it-abbr」を使用するので下記コマンドでインストール後、config.js
に読み込みの記述をします。
$ yarn add -D markdown-it-abbr
module.exports = {
markdown: {
config: md => {
md.use(require('markdown-it-abbr'))
}
}
}
使用する際は下記のような形で記述し、この場合は「HTML」と「W3C」が<abbr>
で括られ、ホバーすると説明が表示されるようになります。
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
The HTML specification is maintained by the W3C.
上のイメージのように装飾した形で表示したい場合は、下記のようなスタイルで実装できます。
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;
}
}
プラグイン:脚注対応
ブログでたまに見る脚注の見栄え・動きをMarkdownで使えるようにします。
実装には「markdown-it-footnote」を使用するので下記コマンドでインストール後、config.js
に読み込みの記述をします。
$ yarn add -D markdown-it-footnote
module.exports = {
markdown: {
config: md => {
md.use(require('markdown-it-footnote'))
}
}
}
使用する際は下記のような形で脚注を設定したい箇所に[^n]
を記述し、その後[^n]
:を先頭に付けて脚注として表示したい内容を入力します。
問題なければ上のイメージのように文章内にリンク設定付きの[1]
や[2]
といった脚注番号が表示され、ページ下部に内容が表示されるようになります。
あのイーハトーヴォ[^1]のすきとおった風、夏でも底に冷たさをもつ青いそら、うつくしい森で飾られたモリーオ市[^2]、郊外のぎらぎらひかる草の波。
[^1]: これは1つ目の脚注です。
[^2]: これは2つ目の脚注です。
プラグイン:ハイライト表示対応
指定箇所がmark
要素で括られてハイライト表示させるようにします。
実装には「markdown-it-mark」を使用するので下記コマンドでインストール後、config.js
に読み込みの記述をします。
$ yarn add -D markdown-it-mark
module.exports = {
markdown: {
config: md => {
md.use(require('markdown-it-mark'))
}
}
}
使用する際は下記のような形で適用させたい前後に==
を記述します。
デフォルトでは背景が黄色ですが、mark
に対してbackground-color
やcolor
のスタイルを指定すれば任意の見栄えにできます。
文章内の一部を==このようにハイライト表示==させることができます。
プラグイン:CodePenとJSFiddleの埋め込み対応
CodePenとJSFiddleの埋め込みを容易にできるようにします。
実装には「markdown-it-playground」を使用するので下記コマンドでインストール後、config.js
に読み込みの記述をします。
$ yarn add -D markdown-it-playground
module.exports = {
markdown: {
config: md => {
md.use(require('markdown-it-playground'))
}
}
}
使用する際はまずCodePenかJSFiddleかを指定し、その後の()
内に各サイトでiframe埋め込みを選択時に表示されるコード内のsrc
部分を記述します。
@[codepen](iframe src)
@[jsfiddle](iframe src)
プラグイン:YouTubeとVimeoの埋め込み対応
YouTubeとVimeoの埋め込みを容易にできるようにします。
実装には「markdown-it-video」を使用するので下記コマンドでインストール後、config.js
に読み込みの記述をします。
$ yarn add -D markdown-it-video
module.exports = {
markdown: {
config: md => {
md.use(require('markdown-it-video'))
}
}
}
使用する際はまずYouTubeかVimeoかを指定し、その後の()
内に表示させたい動画のIDを指定します。
また、動画ID指定だけでなく()
内にURLを記述して指定することもできます。
@[youtube](movie id)
@[vimeo](movie id)
ちなみに、レスポンシブ対応は下記のようなclassやスタイルで可能です。
.embed-responsive {
position: relative;
height: 0;
padding-top: 56.25%;
overflow: hidden;
iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
}
プラグイン:タスクリスト対応
タスクリスト表示をMarkdownで使えるようにします。
実装には「markdown-it-task-lists」を使用するので下記コマンドでインストール後、config.js
に読み込みの記述をします。
$ yarn add -D markdown-it-task-lists
module.exports = {
markdown: {
config: md => {
md.use(require('markdown-it-task-lists'))
}
}
}
下記のような形で記述すれば上のイメージのようなタスクリストが表示され、[ ]
で未チェック、[x]
でチェック済みになります。
- [ ] primary
- [ ] foo
- [x] bar
- [x] baz
- [ ] secondary
- [x] tertiary
- [x] quaternary
- [ ] quinary
タスクリストのマークアップはul
要素なので、場合によってはリストマーカーが表示されます。
これが不要であれば下記のようなスタイルで非表示にできます。
.contains-task-list {
padding-left: 0;
list-style: none;
ul {
padding-left: 1.2em;
}
}
プラグイン:Font Awesome対応
Font AwesomeをMarkdownで使えるようにします。
実装には「markdown-it-task-fontawesome」を使用するので下記コマンドでインストールします。
$ yarn add -D markdown-it-task-fontawesome
インストール後、config.js
にはプラグインの読み込みとhead
内でFont AwesomeのCSSを読み込むための記述をします。(integrity
の値は各自で変更してください。)
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'))
}
}
}
使用する際は、下記のようにアイコン名を:
で括る形で記述します。
:fab-vuejs: x :fab-markdown: = VuePress
デフォルトでもそこまで不便なく使えますが、このように簡単に設定変更したりプラグインで機能追加できるのは嬉しいですね。
markdown-itは他にもプラグインが沢山ありますし、カスタマイズ次第でいろいろできると思うので、自分にピッタリのMarkdown環境を実装してみてください。