メインコンテンツまでスキップ

よくある質問

バグを発見しました。どうしたらよいですか?

ご利用ありがとうございます。まずは直近のマークアップでお困りのはずで、そこを解決したいでしょう。

すぐにできることは、そのルールを無効にすることです。部分的な問題であれば、セレクタを使いながら部分的に無効化することをおすすめします。そうすることで、他のバグが発生していない箇所は有効のままMarkuplint自体は利用を継続できます。

バグ報告はそのあとでも結構です。Issueを作ってもらうのが確実ですが(日本語で構いません)、作者のTwitterにDMを送ったり、「Markuplint」を含んでツイートしてもらえば拾いに行きます。ぜひバグの修正と機能改善にご協力ください。

どう考えてもおかしくないのに警告がでます

バグの可能性が大いに高いですが、その前に確認していただきたいことがあります。

これらは既知の問題ですが、現在のところ対応が難航しています。申し訳ありませんが、部分的にルールの無効化をしてください。

上記以外の問題を発見したら、ご報告ください。

初心者ですが使っても大丈夫ですか?

大丈夫です。初学者こそ利用していただきたいです。しっかりと活用しようとするとNode.jsとコマンドの知識が必要になってしまいますが、VS Codeであれば拡張機能をインストールするだけですぐに利用できます。また、単純に試したいだけであればプレイグラウンドサイトがありますので、お気軽にお試しください。

Markuplintはアクセシビリティチェッカーとして機能しますか?

一部機能しますが、すべてのチェックはできません。Markuplintがサポートするのは主に次のとおりです。

  • HTMLやSVG、WAI-ARIAが仕様に準拠しているかどうか
  • コード上で静的に発見しうるアクセシビリティの問題
  • 設定したプロジェクトのルールに則っているかどうか

アクセシビリティはコードに関わること以外にも、情報設計に関わること、ビジュアルデザインに関わること、そもそもコンテンツや戦略の段階から問題が生まれることがあります。ただ少なくともコードに関わることだけはMarkuplintが担うことで、その他の問題解決に取り組む余裕を生み出すことを期待しています。

HTMLHintやeslint-plugin-jsx-a11yと何が違うの?

できることのいくつかは共通するものがありますが、Markuplintとの大きな差としては次のことが挙げられます。

もちろんHTMLHinteslint-plugin-jsx-a11y、それぞれにしかできないこともあり、どれも導入して併用できますので、適宜プロジェクトにあった利用をしていただけると嬉しいです。

警告が出たコードをどうやって修正したらいいのかわかりません

これはとても難しい質問です。問題の内容によりケースバイケースなので一概に答えられませんが、基本的には必要と言われた要素や属性は追加し、不要と言われた要素や属性は削除します。それによってスタイルの修正を余儀なくされた場合、スタイルを修正してください。スタイルをどの要素に対して施すかは基本的にルールはありません。しかしHTMLの要素や属性にはルールがあります。どちらを優先するのか、ということになりますが、準拠することで得られるメリットはアクセシビリティや互換性など多くあります。修正にかかるコストやメンテナンス管理の問題などプロジェクトにあるかもしれませんが、プロダクトの品質を優先するのであれば積極的に取り組んでいきたいところです。

また、元も子もない話ですが、修正案を考えるにあたってHTMLの知識は必須です。Markuplintから警告を受けた要素や属性から少しずつ調べていって身につけていくと良いでしょう。HTML Standard本体の仕様を調べることが一番良いですが、MDNのドキュメント「HTML の学習: ガイドとチュートリアル」など読みやすいものから調べていってもよいかもしれません。

OGPで怒られます

Open GraphプロトコルはHTMLとは異なる仕様のため、標準で対応していません。対応できる設定例がありますので参考にしてください。

invalid-attrルールで怒られます

invalid-attrはHTMLの仕様に存在しない属性が要素に指定されていると警告します。HTML以外の構文や、フレームワークを利用していると頻繁に遭遇するかもしれません。invalid-attrにはattrsオプションがあり、そこに許可したい属性を追加することで警告をなくすことができます。

また、ReactとVueに関してはスペックプラグインを導入することにより、各構文で独自に使用される属性には警告がでないように定義されています。(参考: なぜスペックプラグインが必要なのですか

もしも構文やフレームワーク(Next.jsNuxtなど)のスペックプラグインがあると便利になるのであればリクエストしてください。

character-referenceルールで怒られます

character-referenceは文字を厳密に評価しません。文字が有効な場所にありエスケープする必要がない場合でも、変更を促されてしまいます。いくつかの構文やテンプレートエンジンでは不都合が起こるかもしれません。その場合、このルール自体を無効化するか、もしくはIssueで状況を報告していただければ対処できるかもしれません。

require-accessible-nameルールで怒られます

アクセシブルな名前はほとんどの場合aria-labelを使ってしまえば解決できますが、最初の解決手段としてそれを使用するのは避けましょうアクセシブルな名前の計算は複雑で、要素によって得られる場所が異なるので、次の表を参考にしてください。

要素主な名前が得られる場所aria-labelの使用
aコンテンツ可能(推奨しない
imgalt属性可能(推奨しない
h1h6コンテンツ可能(推奨しない
buttonコンテンツ可能(推奨しない
tablecaption要素可能(推奨しない
inputlabel要素可能(推奨しない
selectlabel要素可能(推奨しない
textarealabel要素可能(推奨しない
svgなし可能

また、SVG要素に関してほとんどのグラフィック要素はアクセシブルな名前を要求します。

<svg>
<!-- svg要素にアクセシブルな名前が必要 -->
<rect />
<!-- rect要素にアクセシブルな名前が必要 -->
<path />
<!-- path要素にアクセシブルな名前が必要 -->
</svg>

その場合、そのままの要求に従えば、全ての要素に適切なアクセシブルな名前をつけることになります。

<svg aria-label="図形の総合的な名前">
<rect aria-label="図形の一部の矩形の名前" />
<path aria-label="図形の一部の線の名前" />
</svg>

しかし、ほとんどの場合それは現実的な解決方法ではありません。そのため、svg要素にimgロールをつけることによって、プレゼンテーショナルな子の性質を利用して、SVGをひとつの画像と見做すことでアクセシブルな名前をひとつにまとめる解決方法があります。

<svg role="img" aria-label="図形の名前">
<rect />
<!-- rect要素にアクセシブルな名前は要求されない -->
<path />
<!-- path要素にアクセシブルな名前は要求されない -->
</svg>

CLIでglob形式が期待通りに動きません

シェルの種類によってはglob形式の挙動が異なります。MarkuplintのCLIにglob形式を渡したい場合、クォーテーションで囲うのが確実です。

# シェルによって異なり、Markuplint CLIには可変長の文字列としてファイルのフルパスが渡されます
markuplint **/*.html

# Markuplint CLIに文字列として渡されるので確実に内部でglob形式として処理されます
markuplint "**/*.html"

Reactで使えますか?

もちろん使えます。React(JSX)の他に、Vue、Svelte、Astro、Pug、PHPなどに対応しています。利用にはMarkuplintが公式に提供しているプラグインを併用する必要があります。詳しくはHTML以外につかうを御覧ください。

Angularに対応していないようですが?

公式には用意できておりませんが、有志の方がmarkuplint-angular-parserを作ってくださっています。こちらをご利用ください。

対応しているエディタはVS Codeだけですか?

ごめんなさい、公式に対応しているのはVS Codeだけです。かつてはAtomも対応していましたが、現在はVS Codeのみです。VS Code拡張のソースコードは公開しているので、有志による開発がなされることに期待しています。

JSONの出力に対応していますか?

CLIで--formatオプションを使うことでJSONの出力ができます。

markuplint "**/*.html" --format JSON

E2Eテストに利用できますか?

もちろん利用できます。Markuplintはコンポーネント単位のチェックができるように設計されていますが、レンダリングされたHTMLまるごとのチェックも可能です。Markuplintはブラウザとは異なるHTMLパーサを利用するのでHTMLを文字列で渡す必要があります。E2Eテストでの活用方法としては、サーバが返却したHTML文字列か、ブラウザが公開したDOMツリーを文字列に変換し、MarkuplintのAPIに渡すことでチェックできるでしょう。