Markuplintを導入して正しいHTML構文を書こう
正しいマークアップを書くのは本当に大変なこと
アクセシビリティとセマンティック構造を考慮したHTMLを書くことは、SEO対策に必要不可欠。
でも、ブラウザはHTML内に構文エラーを発見しても大抵の場合スルーして問題なく表示してくれるので、意識的に書くのは難しい･･･。
そこでMarkuplintというLinterツールを使って誤った構文に警告を出してくれる環境を作ってみることにしました。
この記事では、なるべく優しくMarkuplintを導入する手順を紹介します。
導入に必要なレベルと作業環境
HTML関連の記事は初学者の方の目にも留まりやすいと思いますので、導入に必要なレベルと作業環境を書いておきます。
必要レベル
・ターミナルをある程度操作できる
・Visual Studio Codeを扱える
・node.jsとnpmをインストールできる
作業環境
・Visual Studio Code v1.89.1
・Ubuntu v23.10
・node v20.13.1
・npm v10.7.0
インストールの手順
手順①Markuplintのインストール
MarkuplintはNode.jsのパッケージとして提供されているので、Node.jsとnpmが必要となります。
ターミナルを開き、以下のコマンドを実行してインストールされているかを確認しましょう。
node -v
npm -v
ここでバージョンを確認できればOKです。
次に、Markuplintのパッケージをインストールします。
npm install --save-dev markuplint
npm install --save-dev @markuplint/html-spec
このとき、node_modules、pakage.json、pakage-look.jsonがディレクトリに追加されるはずです。
正しくインストールされているかを確認してみましょう。
npm show markuplint version
npm show @markuplint/html-spec version
バージョンを確認できればインストールは完了です。
手順②Visual Studio Code拡張機能のインストール
Vscodeを開いて、左サイドバーの拡張機能アイコン（四角いアイコン）をクリックしてください。
検索バーにMarkuplintと入力して、該当する拡張機能をインストールしましょう。
手順③ファイルを作成して設定を追加する
プロジェクトごとにMarkuplintを設定するために、現在作業中のディレクトリに設定ファイルを作成する必要があります。
.markuplintrc、.markuplintrc.jsonまたは、markuplint.config.jsファイルを作成してください。
markuplintrc/.markuplintrc.jsonファイルの場合
{
"extends": [
"markuplint:recommended"
],
"rules": {
"attr-value-quotes": {
"severity": "error",
"value": "double"
}
}
}
markuplint.config.jsファイルの場合
module.exports = {
// 推奨設定を拡張
extends: ['markuplint:recommended'],
// ルールのカスタマイズ
rules: {
// 例：空のalt属性を許可
'required-attr': {
severity: 'error',
value: {
'img': ['alt']
}
},
// 例：特定のタグ内での改行を強制
'newline-per-chars': {
severity: 'warning',
value: {
'p': 80,
'li': 80
}
},
// 例：特定の属性の値をチェック
'attr-value-quotes': {
severity: 'error',
value: 'double'
},
// 例：HTMLファイル内の重複IDを禁止
'id-duplication': true,
// 例：不要なタグを禁止
'void-element-closing': true
},
// カスタムルールを追加する場合（例として）
nodeRules: [
{
tag: 'img',
rules: {
'required-attr': {
severity: 'error',
value: ['src', 'alt']
}
}
}
],
// カスタム設定（必要に応じて）
childNodeRules: [
{
selector: 'div > p',
rules: {
'attr-value-quotes': {
severity: 'error',
value: 'single'
}
}
}
]
};
どちらのファイル記述でも動作しますが、markuplint.config.jsのほうはmodule.exportsを使用するため、より柔軟な設定やカスタマイズが可能になります。
今回はHTMLとCSSのみを扱うProject内での導入説明になるので、.markuplintrc.jsonの使用例を扱っています。
手順④Markuplintを実行する
Visual Studio CodeでProjectを開き、HTMLファイルを編集します。
すると、Markuplintが自動的にコードを検査し、このようなエラーや警告を表示してくれます。
ここまでがインストール手順になります。
トラブルシューティング
ファイルに記述されているルール名を認識しない場合
という、エラーメッセージが出た例を説明します。
この原因は、.markuplintrcファイルに記述されているルール名がMarkuplintの認識するルール名ではないからです。
問題を解決するためには、Markuplintで使用可能なルール名を確認し、正しいルール名を使用する必要があります。
修正前
{
"extends": ["markuplint:recommended"],
"rules": {
"rule-name": true
}
}
修正後
{
"extends": ["markuplint:recommended"],
"rules": {
"attr-value-quotes": {
"severity": "error",
"value": "double"
}
}
}
この例では、rule-nameをattr-value-quotesに置き換えています。正しいルール名を使用することで、エラーを解消しました。
Markuplint公式ドキュメントを参照してルールを確認する必要があるので、難しいですが頑張りましょう･･･。
拡張機能がインストールしたバージョンを認識しない場合
pakage.jsonファイルに記載されたバージョンがv4.9.0なのに、Visual Studio Codeの拡張機能が認識できなかったために、このようなエラーが出る場合があります。
この現象は、拡張機能がnode_modulsを読み込むタイミングがズレてしまった場合に発生します。
大抵の場合は、Visual Studio Codeの再起動か、コマンドパレットからReload Windoswを選択して再読み込みすることで解決します。
もし、解決できなかった場合はpakage.jsonファイルに以下の記述があることを確認してください。
{
"devDependencies": {
"@markuplint/html-spec": "^4.8.0",
"markuplint": "^4.9.0",
}
この場合は、"markuplint": "^4.9.0"が該当する記述です。
Markuplintが正しくインストールされなかった場合
別のnpmパッケージがインストールされている状態でMarkuplintを導入しようとする場合に発生しやすいです。
この原因は、パッケージ同士のバージョンや依存関係によって異なる場合があります。
私が遭遇したものだと、
内部的に同じ依存関係にあるパッケージ同士がMarkuplintのインストールによって競合
↓
変更が入ったときに拡張機能が初回ロード時の情報を読み込むことが出来ず警告が発生する
と、ややこしいことになってました。
この場合は手動で、
・pakage.jsonファイルのバージョン記述を調整する
・node_modulesとpakage-look.jsonを一度削除しパッケージをすべて再インストールする
などを行う必要があるので、大変です･･･。
おわりに
導入自体は、コマンドをひとつひとつ実行していくだけなので比較的簡単です。
各ファイルの設定やパッケージ同士が競合してしまった場合の対応には、より専門的なnode.jsやnpm知識が必要になってきますが、処理全体の流れを把握できればきっと大丈夫。
もし、エラーが発生してしまっても焦らずに対処していけば解決できるでしょう。
Discussion