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

コマンドラインインターフェイス

使い方​

$ markuplint target.html
$ markuplint target.html target2.html
$ markuplint "**/*.html"

CLIはターゲットとなるHTMLファイルを可変長引数として受け取ります。また、glob形式も受け付けます。

-を指定すると標準入力からソースを読み込みます。出力がパイプでも使えます。ファイルパス、--search、--fix、--suppress、--suppress-rule、--prune-suppressionsとは併用できません(修正後のソースを書き出すファイルも、抑止を記録するファイルもないためです)。入力の終端(端末ではCtrl-D)まで待ちます。入力が空の場合は、空のソースとして検査します。-という名前のファイルを検査するときは./-と書きます。

引数をまったく指定しない場合、標準入力を読み込むのは出力が端末のときだけです(例: cat target.html | markuplint)。出力もパイプにするときは-を指定してください。-が併用できないオプションは、この場合も併用できません。

$ cat target.html | markuplint - --format JSON | jq

エラーがあった場合、または--no-allow-warningsの指定時に警告があった場合や警告数が--max-warningsを超えた場合は終了コード1を返し、それ以外は0を返します。終了コードは--formatの指定(JSONを含む)によって変わりません。

--fixを指定した場合、終了コードは修正後の出力に残っている問題を反映します。すべての問題が修正された場合は0を返します。--fix-dry-runはファイルを変更しないため、終了コードはディスク上のファイルの状態を反映します。

オプション​

正規形オプション省略形オプション引数デフォルト値解説
--config-cファイルパスなし設定ファイルのパス。自動検索は行われません
--fixなしなしfalseルールが対応していれば対象ファイルを修正します
--fix-dry-runなしなしfalse--fix の変更内容をファイルを変更せずにプレビューします
--format-fJSON、Simple、GitHubもしくはStandardStandard出力形式
--no-search-configなしなしfalse設定ファイルを自動で検索しません
--ignore-extなしなしfalse拡張子の種類に関わらず受け取ったファイルを評価します
--no-import-preset-rulesなしなしfalse組み込みルールを利用しません
--localeなし言語コード(例:ja)OS設定によるメッセージの言語
--no-colorなしなしfalse出力をカラーリングしません
--problem-only-pなしfalse違反結果のみ出力します
--allow-warningsなしなしtruewarningではステータスコード0を返します
--no-allow-empty-inputなしなしfalseファイルが見つからなかった場合にステータスコード1を返します
--show-confignone値なし, details値なし対象ファイルの適用された設定を出力します
--verboseなしなしfalse詳細な情報も同時に出力します
--include-node-modulesなしなしfalsenode_moduleディレクトリ内のファイルを含めて評価します
--severity-parse-errorなしerror、warningもしくはofferrorパースエラーの深刻度レベルを指定します
--max-countなし数値0表示する違反数を制限します(終了コードは対象外)。0で無制限
--max-warningsなし数値-1警告数の上限を設定します。-1は制限なしを意味します
--no-progressive-outputなしなしfalse全ファイルの処理完了を待ってから結果をまとめて出力します
--suppressなしなしfalse[実験的] 現在の全エラー違反をsuppressionsファイルに記録します
--suppress-ruleなしルールIDなし[実験的] 指定ルールの違反のみ記録します
--prune-suppressionsなしなしfalse[実験的] suppressionsファイルから不要なエントリを削除します
--suppressions-locationなしファイルパスmarkuplint-suppressions.json[実験的] suppressionsファイルのカスタムパス

Particular run​

--help​

ヘルプを出力します。(省略形オプション: -h)

--version​

バージョンを出力します。(省略形オプション: -v)

--init​

初期化をします。設定ファイルをつくり、モジュールをインストールします。

$ npx markuplint --init

質問に対話的に答えることで、必要なモジュールをインストールします。

--max-count​

出力に表示される違反数を制限します。制限に達すると、残りのファイルの違反は表示されず、出力で「skipped」としてマークされます。これらのファイルもチェックされるため、違反は終了コードに数えます。このオプションは特に、多くの違反がある既存プロジェクトにMarkuplintを導入する際に、圧倒的な出力を管理するのに役立ちます。

# 最初の10件の違反のみを表示
$ markuplint "**/*.html" --max-count=10

# 最初の違反のみを表示
$ markuplint index.html --max-count=1

# 制限なし(デフォルトの動作)
$ markuplint index.html --max-count=0

主な機能:

  • 段階的導入: 管理可能な数の問題に集中することで段階的な改善を可能に
  • 情報表示: 違反が切り詰められた場合に情報メッセージを表示(標準形式のみ)
  • 形式互換性: すべての出力形式(--format=json、--format=simpleなど)でシームレスに動作
  • 修正互換性: --fixまたは--fix-dry-runと併用する場合、完全な修正を保証するため制限は無視される
  • 終了コード: 制限が決めるのはレポートに表示する内容であり、終了コードではありません。すべてのファイルがチェックされ、制限で隠れる違反や「skipped」と表示されたファイルの違反も含めて数えます
  • suppressions互換性: suppressionsファイルで抑制された違反は制限に数えません。--suppressと--prune-suppressionsは制限を無視するため、ファイルには実行全体で見つかった内容が記録・整理されます

段階的改善の使用例:

  1. 現在の違反数を確認: markuplint "**/*.html" | wc -l で現在の違反数をカウント
  2. 制限を設定: CIで markuplint "**/*.html" --max-count=50 を実行
  3. 徐々に違反を修正し、制限値を減らしていく
  4. すべての違反が修正されたら最終的に制限を削除

注意: 制限により違反が表示されなかったファイルは、出力で「skipped」としてマークされ、どのファイルが報告されなかったかが明確にわかります。これらのファイルもチェックされ終了コードに数えるため、制限を設けても違反のある実行が成功になるわけではありません。既存の違反があってもCIを通すには、--suppressまたは--max-warningsを使ってください。

--max-warnings​

警告数の上限を設定します。警告数が指定した上限を超えた場合、Markuplintは非ゼロの終了コードで終了します。このオプションは既存プロジェクトでのMarkuplintの段階的導入に特に有用です。

# 警告を10個まで許可
$ markuplint "**/*.html" --max-warnings=10

# 警告を許可しない(厳密モード)
$ markuplint index.html --max-warnings=0

# 制限なし(デフォルトの動作)
$ markuplint index.html --max-warnings=-1

主な機能:

  • 段階的導入: 警告の閾値を設定することで段階的な改善を可能に
  • ファイル横断集計: 処理されるすべてのファイルの警告数をカウント
  • CI統合: 継続的統合での警告制限設定に最適
  • エラー優先: 警告制限に関係なく、エラーは常に非ゼロ終了コードを引き起こします

段階的改善の使用例:

  1. 現在の警告を確認: markuplint "**/*.html" --allow-warnings ですべての警告を確認
  2. 初期制限を設定: CIで markuplint "**/*.html" --max-warnings=50 を設定
  3. 徐々に警告を減らし、制限値を下げていく
  4. 最終的に --max-warnings=0 で警告ゼロを達成

--no-progressive-output​

デフォルトでは、すべてのファイルの処理完了を待つ代わりに、各ファイルの処理完了後に即座に結果を出力します。これにより、大量のファイルを処理する際にリアルタイムフィードバックを提供し、CLIがフリーズしているように見えることを防ぎます。従来の一括出力に戻すには --no-progressive-output を指定してください。

# 各ファイルの処理完了後に即座に結果を出力(デフォルト)
$ markuplint "**/*.html"

# すべてのファイルの処理完了を待ってから結果をまとめて出力
$ markuplint "**/*.html" --no-progressive-output

主な機能:

  • リアルタイムフィードバック: 各ファイルの処理完了と同時に結果を確認
  • UX向上: 大量ファイル処理中のCLIフリーズ感を防止
  • JSON形式例外: JSON出力はこの設定に関係なく常に一括モードを使用
  • --max-count例外: --max-countを指定した場合、上限はファイル単位ではなく実行全体に適用されるため、実行全体が一括モードにフォールバックします
  • パフォーマンス: パフォーマンスへの影響はなく、出力タイミングのみ変更

--no-progressive-outputを使う場面:

  • 従来の一括サマリー出力をパースするスクリプト
  • v4の出力順序を再現したい場合

--suppress / --suppress-rule​

実験的機能

この機能は実験的であり、今後のリリースで変更される可能性があります。

既存の違反をsuppressionsファイルに記録し、新規コードに対してのみルールを適用します。詳しくは一括抑制を参照してください。

# 現在の全エラー違反を抑制
$ markuplint "**/*.html" --suppress

# 特定のルールのみ抑制
$ markuplint "**/*.html" --suppress-rule no-duplicate-attr

# カスタムパスでsuppressionsファイルを指定
$ markuplint "**/*.html" --suppress --suppressions-location .config/suppressions.json

--prune-suppressions​

実験的機能

この機能は実験的であり、今後のリリースで変更される可能性があります。

修正済みの違反に対応する不要なエントリをsuppressionsファイルから削除します。

$ markuplint "**/*.html" --prune-suppressions

次のステップ​

  • コードを無視する — 違反の抑制、特定の要素やファイルのルール無効化
  • 設定 — 設定ファイルの形式とプロパティ
  • FAQ — よくある質問とトラブルシューティング