markdown linting accessibility スタイルガイド documentation

Markdown Lintガイド:よくある15の問題と修正方法

スキップされた見出し、欠落している画像代替テキスト、裸の URL、壊れたコード フェンス、一貫性のないリスト、不正な形式のテーブルなど、一般的な Markdown の問題を見つけて修正します。

W
WordToMD チーム
·

Markdown は許容されます。構造的な間違いのあるドキュメントが表示される可能性があるため、表が壊れたり、ナビゲーションから見出しが消えたり、スクリーン リーダー ユーザーにとって画像が意味を持たなくなるまで、それらの間違いは見落とされやすくなります。

Markdown lint は、公開前にソース テキストの構造、アクセシビリティ、一貫性の問題をチェックするプロセスです。から始めてください Markdownリンター は、スキップされた見出しレベル、欠落している画像代替テキスト、裸の URL、ラベルのないまたは閉じられていないコード フェンス、および末尾の空白を検出します。次に、このガイドの手動チェックリストを使用して、より広範な編集レビューを行ってください。

リンティングは、任意の設定を強制するものではありません。有用なルールは、実際の読み取り、レンダリング、メンテナンス、またはアクセシビリティの問題を防止する必要があります。

公開前クイックチェックリスト

チェックなぜそれが重要なのか自動ですか、それとも手動ですか?
見出し階層文書構造を保持しますリンター
画像の代替テキスト視覚がなくても画像を理解できるようにしますリンター
説明リンクアクセシビリティとスキャンの向上リンター + 手動レビュー
閉鎖されたコードフェンスページの残りの部分がコードになるのを防ぎますリンター
コード言語ラベル便利な構文の強調表示を有効にしますリンター
末尾の空白目に見えない方言特有の動作を回避しますリンター
1 つの明確なページ タイトルページの目的を明確に保つマニュアルレビュー
一貫したリストネストの破損を防止しますマニュアルレビュー
有効なテーブル列構造をそのまま維持しますマニュアルレビュー
固有の見出しアンカーの重複による混乱を防止しますマニュアルレビュー
ポータブル HTML の使用法レンダラー固有のエラーを回避しますマニュアルレビュー
読みやすい段落理解力が向上しますマニュアルレビュー

代表的なドキュメントをリンターに貼り付け、チェックを実行し、報告された行を修正してから、実際の発行システムで完全なページをプレビューします。

1. スキップされた見出しレベル

問題

# Deployment Guide

### Configure credentials

ドキュメントは H1 から H3 にジャンプします。目に見える信号がフォント サイズだけである場合は、許容範囲内に見えるかもしれませんが、構造的なアウトラインにレベルが欠けています。

修正

# Deployment Guide

## Configure credentials

見出しは、視覚的なサイズを選択するためではなく、階層を説明するために使用します。「資格情報の構成」が欠落しているセクション内に本当に属している場合は、そのセクションを追加します。

# Deployment Guide

## Preparation

### Configure credentials

について Markdownリンター は、1 レベル以上ジャンプする見出しを報告します。

2. H1 見出しが複数または欠落している

通常、ページには 1 つの明確なタイトルが必要です。H1 を前付から生成するドキュメント システムもあれば、Markdown 本文で H1 を生成することを期待するドキュメント システムもあります。サイトでどの規則が使用されているかを確認してください。

出典があいまいです

# Installation

# Configuration

出典を明確にする

# Product setup

## Installation

## Configuration

サイト テンプレートがレンダリングされる場合 title: Product setup ページ H1 と同様に、本文は代わりに H2 で始まる場合があります。ルールは、「すべてのMarkdown ファイルに 1 つだけ含まれなければならない」というものではありません。 #.” The rule is “the rendered page needs one unambiguous primary heading.”

3. 強調のみに使用される見出し

このソースは不要なアウトライン エントリを作成します。

#### Important!

テキストでセクションが紹介されていない場合は、散文または適切な吹き出しを使用します。

**Important:** Back up the database before continuing.

見出しは、読者がナビゲートしやすいようにする必要があります。装飾的な見出しがあると目次が煩雑になり、ナビゲーション支援の有用性が低下します。

4. 代替テキストのない画像

問題

![](architecture.png)

画像には代替テキストがありません。それを見ることができない読者には何の説明も受けられず、壊れた画像や無効な画像を閲覧している人はその目的を判断することができません。

修正

![Request flow from the browser through the API gateway to the orders service](architecture.png)

画像の外観だけではなく、画像がもたらす情報について説明します。媒体が重要でない限り、「~のイメージ」などのフレーズは避けてください。

装飾的な画像は特殊なケースです。画像が情報を伝えない場合、空の代替テキストは HTML で正しい場合がありますが、Markdown レンダラーとコンテンツ ワークフローは異なります。画像が純粋に装飾的なものである場合は、まずそれが技術文書に属するかどうかを確認してください。

リンターは、空の代替テキストを含む Markdown 画像にフラグを立てます。の 画像フォーマッター は、明示的な代替およびオプションのキャプションを含む画像マークアップを生成できます。

問題

Visit https://example.com/docs/setup for more information.

裸の URL はスキャンするのが難しく、声に出して読むと不快になる場合があります。一般的なリンク テキストの方が優れているわけではありません。

[Click here](https://example.com/docs/setup).

修正

Read the [service setup guide](https://example.com/docs/setup).

説明リンクは、何を開くか読者に伝えます。これらは、リンクのリストに抽出された場合にも意味を持ちます。

リンターは多くのベアを識別します http:// and https:// URL ですが、リンク テキストが有用かどうかを判断するには編集上のレビューが必要です。

6. 閉じられていないコードフェンス

問題

```javascript
const status = 'ready';

## Next section

終了フェンスがないと、レンダラーはページの残りの部分をコードとして扱う可能性があります。

修正

```javascript
const status = 'ready';
```

## Next section

フェンスが閉じられていないと、有効な文書の大部分が破損する可能性があります。リンターは、一致しないフェンスが始まるラインを報告します。

7. 言語識別子のないコードフェンス

あまり役に立たない

```
npm run build
```

より良い

```bash
npm run build
```

言語識別子は、構文の強調表示を有効にし、読者に表示されているコンテンツの種類を伝えます。次のような共通の識別子を使用します。 javascript, typescript, json, html, css, bash, powershell, yaml、または markdown.

色を取得するためだけに不正確な言語を追加しないでください。非構造化出力の場合は、次を使用します。 text 宛先がそれを認識した場合。

8. 一貫性のないリストのインデント

問題

- Install dependencies
    - Production packages
  * Development packages
	- Optional tools

タブ、スペース、マーカーが混在していると確認が難しく、異なるレベルでレンダリングされる可能性があります。

修正

- Install dependencies
  - Production packages
  - Development packages
  - Optional tools

プロジェクトに対して一貫したインデント幅を選択します。スペースの正確な数は、Markdown の方言とリストの内容によって異なりますが、一貫性が重要です。

コンピュータの ネストリストフォーマッター は、最終レビューの前に混合箇条書き、番号付け、タブ、およびインデントを正規化します。

9. 手動で入力された数値シーケンス

長い番号付きリストは維持にコストがかかります。

1. Download the package.
2. Verify the checksum.
3. Install the package.
4. Restart the service.

多くのMarkdown レンダラーでは、すべてのアイテムの使用が許可されています 1. 順序付けされたシーケンスを表示したまま:

1. Download the package.
1. Verify the checksum.
1. Install the package.
1. Restart the service.

これにより、ソース diff の再番号付けノイズが軽減されます。ただし、説明で「ステップ 3」を参照する場合は、ソースに明示的に番号を付けた方が議論が容易です。プロジェクトの規則を 1 つ選択し、それを一貫して適用します。

入力された数字、順序付きリスト マーカー、および段落テキストを組み合わせないでください。ネストされたステップを編集した後、レンダリング結果を確認します。

10. 不正な形式のテーブル

問題

| Name | Status | Owner |
| --- | --- |
| Search | Ready | Maya |
| Billing | Review |

セパレータ行とデータ行に同じ論理数の列が含まれていません。

修正

| Name | Status | Owner |
| --- | --- | --- |
| Search | Ready | Maya |
| Billing | Review | Unassigned |

セル内のエスケープされていないパイプ文字もチェックします。

| Command | Description |
| --- | --- |
| `test \| deploy` | Run the matching stage |

について Markdownテーブルフォーマッター は、不均一な行を露出し、整列したソースを生成するのに役立ちます。新しいテーブルを視覚的に作成するには、 Markdown テーブルジェネレーター.

11. 重複した見出しとアンカーの衝突

ドキュメントでは、「例」などの目に見える見出しを正当に繰り返すことができますが、自動的に生成されたアンカー ID は、 #examples, #examples-1、および #examples-2。正確なルールはレンダラーによって異なります。

見出しを繰り返すと手動リンクが脆弱になります:

- [API examples](#examples)
- [CLI examples](#examples)

説明的な見出しを好みます:

## API examples

## CLI examples

次に、次の内容で目次を生成します。 Markdown 目次ジェネレーター を参照し、ターゲット プラットフォームのアンカーを確認します。

12. 末尾の空白

行末のスペースは表示されません。一部の Markdown 方言では、末尾の 2 つのスペースによって強制改行が作成されます。これは、エディターの誤った操作によってレンダリングが変更される可能性があることを意味します。

リンターは末尾の空白を報告するため、それが意図的であるかどうかを判断できます。段落の区切りには空行を入れてください。本当に改行が必要な場合は、プロジェクトで選択した規則を一貫して文書化して適用してください。

編集者は通常、保存時に末尾の空白を自動的に削除できますが、これによって従来のコンテンツの意図的な改行が変更されないことを確認してください。

13. 移植性を損なう生のHTML

Markdown では、多くの場合、埋め込み HTML が許可されます。

<div class="warning-panel">
  Restarting the service ends active sessions.
</div>

そのブロックは、ある Web サイトでは機能しても、他の Web サイトではエスケープ、サニタイズ、または間違ったスタイルにされる可能性があります。同じ意味を表現できる場合は、ポータブル Markdown を優先します。

> **Warning:** Restarting the service ends active sessions.

制御された画像サイズやサポートされている画像など、Markdown では表現できない機能には意図的に HTML を使用します。 <details> ブロック。コンテンツをレンダリングし、それぞれをテストする必要がある宛先のリストを保持します。

について コールアウト ジェネレーター は、移植性がネイティブ表現よりも重要でない場合、GitHub、Obsidian、および MkDocs のプラットフォーム固有の構文を生成できます。

14. 長すぎる段落とスキャン性の悪さ

Markdown は構造的には有効ですが、それでも読み取りにくい場合があります。いくつかの決定、警告、手順を含むテキストの壁を再編成する必要があります。

使用:

  • 1 つの主要なアイデアに関する短い段落。
  • ナビゲーションのための説明的な見出し。
  • は並行品目のリストです。
  • 純粋に比較可能なフィールドのテーブル。
  • リテラル入力および出力用のコード ブロック。
  • では、少数の重要な例外について説明します。

すべての文を箇条書きにしないでください。リストは、項目が同じ文法的および概念的な役割を持っている場合に最も効果的に機能します。

使用する 文字数・読了時間 を使用して、段落数、見出し数、および読み上げの長さを検査しますが、統計をターゲットではなくシグナルとして扱います。

15. 互換性プランのないレンダラー固有の構文

GitHub タスク リスト、Obsidian wiki リンク、MkDocs 警告、脚注、定義リスト、および前付はすべて便利ですが、どこでも同じようにサポートされているわけではありません。

例えば:

> [!NOTE]
> This callout is useful in destinations that recognize the syntax.

拡張機能を採用する前に、次の 3 つの質問に答えてください。

  1. 最終出力を所有するレンダラーはどれですか?
  2. コンテンツは後で別の場所に移動する必要がありますか?
  3. 拡張機能がサポートされていない場合、読者には何が表示されますか?

移植可能な Markdown 基盤を維持し、可能であれば公開エッジにプラットフォーム構文を追加します。

実践的なリンティングワークフロー

ステップ 1: 構造を確認する

ソースを Markdownリンター。最初にエラーを修正し、次に警告、次に情報の一貫性項目を修正します。自動チェックでは場所を特定する必要があります。黙って意味を書き換えるべきではありません。

ステップ 2: 難しい要素を正規化する

機械的クリーンアップには重点を置いたツールを使用します。

集中的な変更により、ファイル全体を書き換える広範なフォーマッタよりも小さくてレビューしやすい差分が生成されます。

ステップ 3: ドキュメントをプレビューする

でソースを開きます。 Markdown 編集者 を参照し、Markdown をレンダリングされた出力と比較します。確認してください:

  • の見出しと目次。
  • リストとタスクリスト。
  • テーブルを狭い画面に表示します。
  • 画像とリンク。
  • コード ブロックとインライン コード。
  • コールアウトまたは生の HTML。

ステップ 4: 実際の宛先をテストする

一般的なプレビューでは、すべてのレンダラーを再現することはできません。公開する前に、GitHub、Obsidian、GitLab、MkDocs、または実際のドキュメント サイトでファイルを開きます。

ステップ 5: 構文だけでなく意味を確認する

リンターは、手順が安全かどうか、リンクが意図したポリシーを指しているか、画像の説明が重要な結論を伝えているかどうかを判断できません。人間の査読者は、正確さ、完全性、トーン、および聴衆の適合性を確認する必要があります。

チーム スタイル ガイドの推奨事項

文書化された短い約束事は、暗黙の好みを何十も記すより効果的です。定義:

  • ページのタイトルが前付にあるか、Markdown 本文にあるか。
  • 許可される見出しの進行。
  • リストのインデントと順序付きリストのスタイル。
  • コードフェンス言語要件。
  • 画像と代替テキストがどのようにレビューされるか。
  • テーブルの複雑さの制限。
  • は HTML とプラットフォーム拡張を許可しました。
  • 行の最大長 (チームが使用する場合)。
  • リンクのチェック方法。
  • リンター ルールが公開をブロックします。

実際の欠陥を防ぐルールから始めます。チームが解決する問題を理解している場合にのみ、ルールを追加します。

FAQ

有効なMarkdownは自動的にアクセス可能ですか?

いいえ。有効な構文には、空の代替テキスト、曖昧なリンク、紛らわしい見出し、アクセスできない図、不適切な読み上げ順序が含まれる場合があります。アクセシビリティには構造的および編集上のレビューが必要です。

Markdown リンターは私の文書を書き換えますか?

WordToMD リンターは行番号付きの問題を報告します。ソースをサイレントに書き換えることはないため、各修正を制御することができます。

なぜリンターは裸の URL を報告するのでしょうか?

説明的なリンク テキストはスキャンしやすく、支援技術にとってより便利です。リテラルアドレスが読者に必要な情報でない限り、URL を意味のあるラベルに置き換えます。

ラベルのないコードフェンスは常に間違っているのでしょうか?

常にではありませんが、通常、正しい言語識別子を使用すると、明瞭さと構文の強調表示が向上します。使用する text は、サポートされている場合、不正確なプログラミング言語を割り当てる代わりに、プレーンな出力を示します。

すべてのプロジェクトで同じ lint ルールを使用する必要がありますか?

いいえ。GitHub README、Obsidian ボールト、API リファレンス、および発行サイトには異なる規則があります。構造ルールとアクセシビリティ ルールのコア セットを共有し、目的地固有のチェックを追加します。

リンティングは校正の代わりに使用できますか?

いいえ。リンターはパターンを検出します。技術的な真実性、議論の質、ユーザーの意図、または文が文脈の中で理解できるかどうかを確実に検証することはできません。

結論

良い Markdown は、たまたまレンダリングされたソース以上のものです。明確な概要、意味のあるリンク、アクセス可能な画像、完全なコード フェンス、一貫したリスト、有効なテーブル、および公開プラットフォームとの定義された関係があります。

を実行します。 Markdownリンター を使用して構造を迅速にチェックするには、 Markdown 編集者 を視覚的なレビューに使用し、ソースの保守が容易になる場所にのみ焦点を当てたフォーマッタを適用します。その結果、移植性が高く、アクセスしやすく、将来の編集で信頼できる Markdown が完成しました。