[all-commits] [llvm/llvm-project] bebff2: [docs] Prefer colon fences to delineate blocks con...

[Reid Kleckner via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: bebff2a2e93c8c0db4b4cb94b504166e345d19e3
      https://github.com/llvm/llvm-project/commit/bebff2a2e93c8c0db4b4cb94b504166e345d19e3
  Author: Reid Kleckner <rkleckner at nvidia.com>
  Date:   2026-08-08 (Sat, 08 Aug 2026)

  Changed paths:
    M clang/docs/LanguageExtensions.md
    M clang/docs/LifetimeSafety.md
    M clang/docs/MisExpect.md
    M clang/docs/ReleaseNotes.md
    M clang/docs/ReleaseNotesTemplate.txt
    M clang/docs/Toolchain.md
    M flang/docs/FAQ.md
    M flang/docs/GettingStarted.md
    M flang/docs/ReleaseNotes.md
    M flang/docs/ReleaseNotesTemplate.txt
    M lldb/docs/use/aarch64-linux.md
    M llvm/docs/AMDGPUMemoryModel.md
    M llvm/docs/AliasAnalysis.md
    M llvm/docs/BitCodeFormat.md
    M llvm/docs/BuildingADistribution.md
    M llvm/docs/CMake.md
    M llvm/docs/CodeGenerator.md
    M llvm/docs/CodingStandards.md
    M llvm/docs/CommandLine.md
    M llvm/docs/CompilerWriterInfo.md
    M llvm/docs/Contributing.md
    M llvm/docs/Coroutines.md
    M llvm/docs/CoverageMappingFormat.md
    M llvm/docs/DeveloperPolicy.md
    M llvm/docs/ExceptionHandling.md
    M llvm/docs/GettingStarted.md
    M llvm/docs/GettingStartedVS.md
    M llvm/docs/GitHub.md
    M llvm/docs/HowToBuildWithPGO.md
    M llvm/docs/HowToCrossCompileLLVM.md
    M llvm/docs/InstrProfileFormat.md
    M llvm/docs/LangRef.md
    M llvm/docs/Lexicon.md
    M llvm/docs/MIRLangRef.md
    M llvm/docs/MemProf.md
    M llvm/docs/Passes.md
    M llvm/docs/ProgrammersManual.md
    M llvm/docs/ReleaseNotes.md
    M llvm/docs/ReleaseNotesTemplate.txt
    M llvm/docs/Remarks.md
    M llvm/docs/SourceLevelDebugging.md
    M llvm/docs/SphinxQuickstartTemplate.md
    M llvm/docs/TestSuiteGuide.md
    M llvm/docs/TestingGuide.md
    M llvm/docs/WritingAnLLVMNewPMPass.md
    M llvm/docs/WritingAnLLVMPass.md
    M llvm/docs/index.md

  Log Message:
  -----------
  [docs] Prefer colon fences to delineate blocks containing markup (#214921)

Myst has an extension,
[colon_fence](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#syntax-colon-fence),
that we enable in our docs. There are many Markdown-aware tools out
there that know to interpret triple backtick as a code block fence, so
they highlight them as pre-formatted text. Colon fences are an
unrecognized Myst extension, and if the Sphinx directive contains a
block of markdown formatted text, that's the desired behavior.
Therefore, at some point during the migration, I started using them.
However, I didn't document this guideline, and I didn't apply it
consistently to the early docs. This PR does that: documents the
guideline, and applies it to our docs.

After this change:
```
❯ rg '```\{(option|note|todo|admonition|warning)\}' | cut -d / -f 1 | sort | uniq -c
     72 clang-tools-extra
```

The generated HTML was byte-identical.

I plan to leave clang-tools-extra untouched since there are PRs in
flight.

LLM-assisted



To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications