Skip to content

docs: fix markdown-structure warnings in guide docs#176

Merged
ootakazuhiko merged 2 commits into
mainfrom
fix/markdown-structure-fence-language-20260212
Feb 12, 2026
Merged

docs: fix markdown-structure warnings in guide docs#176
ootakazuhiko merged 2 commits into
mainfrom
fix/markdown-structure-fence-language-20260212

Conversation

@ootakazuhiko

@ootakazuhiko ootakazuhiko commented Feb 12, 2026

Copy link
Copy Markdown
Collaborator

Pull Request

目的

  • 何を直す/追加するか:
    • markdown-structure 警告(コードフェンス言語未指定 / 複数H1)を解消する

変更内容(概要)

  • docs/diagram/ai_diagram_guidelines.md の言語未指定コードフェンスに text を付与
  • docs/diagram/svg_style_guide.md の言語未指定コードフェンスに text を付与
  • docs/diagram/svg_style_guide.md の closing fence 誤り(text になっていた箇所)を ` ` に修正
  • tech-book-writing-6phases.md の言語未指定コードフェンスに text を付与
  • src/chapter-introduction/index.md / docs/chapters/chapter-introduction/index.md の言語未指定コードフェンスに text を付与
  • project-management/structure-review-round1.md の H1 を1つに統一(残りを H2 へ変更)

影響範囲

  • 影響する:上記6ファイル(いずれも文書の構造メタ情報)
  • 影響しない:章本文の意味、実装コード、CIロジック

QA(必須)

Pages確認(原則必須)

検証

  • 自動テスト:node ../book-formatter/scripts/check-markdown-structure.js . --fail-on warn(issues 0)
  • 手動確認:変更差分が言語指定付与・見出しレベル調整のみであることを確認

ロールバック

  • 失敗時の戻し方:本PRをrevertして元状態に戻す

関連Issue

AI支援の開示(任意)

  • AI支援:有
  • 利用範囲:実装補助 / レビュー補助
  • 人間が最終確認した観点:構造警告の解消、差分の妥当性、CI結果

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR aims to eliminate check-markdown-structure warnings in documentation by adding explicit code-fence languages and normalizing headings to avoid multiple H1s.

Changes:

  • Add text language identifiers to previously-untyped fenced code blocks across multiple docs.
  • Normalize project-management/structure-review-round1.md to a single H1 by demoting subsequent H1s to H2.
  • (Intended) update diagram docs to satisfy markdown-structure lint rules.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Show a summary per file
File Description
tech-book-writing-6phases.md Adds text to fenced blocks used for non-code examples.
src/chapter-introduction/index.md Adds text to the directory-tree example fence.
docs/chapters/chapter-introduction/index.md Mirrors the same text fence update as src/.
project-management/structure-review-round1.md Demotes extra H1 headings to H2 to ensure only one H1.
docs/diagram/svg_style_guide.md Attempts to add text to untyped fences, but currently breaks multiple code-fence closings.
docs/diagram/ai_diagram_guidelines.md Adds text to many fenced blocks containing prompt templates and checklists.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/diagram/svg_style_guide.md Outdated
Comment thread docs/diagram/svg_style_guide.md Outdated
Comment thread docs/diagram/svg_style_guide.md Outdated
Comment thread docs/diagram/svg_style_guide.md
Comment thread docs/diagram/svg_style_guide.md
Comment thread docs/diagram/svg_style_guide.md
Comment thread docs/diagram/svg_style_guide.md Outdated
@ootakazuhiko

Copy link
Copy Markdown
Collaborator Author

レビュー本文およびインライン7件(suggestion含む)を全件確認しました。

  • 必要対応: 7件すべて対応
  • 対応内容: docs/diagram/svg_style_guide.md の closing fence 誤り(text になっていた箇所)を に修正し、言語指定は opening fence 側へ統一
  • 対応コミット: 89d5467
  • 検証: check-markdown-structure warnings=0、CI(qa / docs-quality-gate / docs-forbidden)PASS

各インラインコメントには返信済みで、スレッドは解決済みです。

@ootakazuhiko
ootakazuhiko merged commit 955f048 into main Feb 12, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants