From 7a823faa47e44fec79bfdb9cdff2d1981e68258b Mon Sep 17 00:00:00 2001
From: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com>
Date: Wed, 15 Jul 2026 18:05:14 -0700
Subject: [PATCH] chore: sync markdown instructions to radius and ai-extensions

Bring the markdown authoring instructions over from radius-project/radius into sync-templates and add a sync mapping that distributes markdown.instructions.md to both radius-project/radius and radius-project/ai-extensions.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 9c407214-7278-4927-90ca-077274e4096c
Signed-off-by: Brooke Hamilton <45323234+brooke-hamilton@users.noreply.github.com>
---
 .github/sync.yml                              |  7 +++++
 .../instructions/markdown.instructions.md     | 31 +++++++++++++++++++
 2 files changed, 38 insertions(+)
 create mode 100644 sync-templates/.github/instructions/markdown.instructions.md

diff --git a/.github/sync.yml b/.github/sync.yml
index 3f217dd..a1939a1 100644
--- a/.github/sync.yml
+++ b/.github/sync.yml
@@ -97,6 +97,13 @@ group:
       - source: sync-templates/.github/instructions/shell.instructions.md
         dest: .github/instructions/shell.instructions.md
 
+  - repos: |
+      radius-project/radius
+      radius-project/ai-extensions
+    files:
+      - source: sync-templates/.github/instructions/markdown.instructions.md
+        dest: .github/instructions/markdown.instructions.md
+
   # Spellcheck (cspell) config and workflow for the documentation-heavy repos.
   # Destination workflow keeps the existing `.yaml` extension so it overwrites
   # the per-repo workflow instead of creating a duplicate.
diff --git a/sync-templates/.github/instructions/markdown.instructions.md b/sync-templates/.github/instructions/markdown.instructions.md
new file mode 100644
index 0000000..ae1fb42
--- /dev/null
+++ b/sync-templates/.github/instructions/markdown.instructions.md
@@ -0,0 +1,31 @@
+---
+description: 'Conventions for authoring Markdown in this repository'
+applyTo: '**/*.md'
+---
+
+<!--
+  This file is synced from the radius-project/.github repository.
+  DO NOT EDIT MANUALLY - changes will be overwritten by the next sync.
+  Source: https://github.com/radius-project/.github
+-->
+
+# Markdown Guidelines
+
+Formatting rules for Markdown are enforced by tooling. This file covers only the conventions the linters cannot check and points to the source of truth for everything else.
+
+## Source of truth
+
+Do not restate or duplicate lint rules here — change the configuration instead, otherwise this file will drift from what is actually enforced.
+
+- **Rules:** `markdownlint-cli2`, configured by [`.github/linters/.markdownlint-cli2.yaml`](../linters/.markdownlint-cli2.yaml), which extends [`.github/linters/.markdownlint.yml`](../linters/.markdownlint.yml).
+- **Tables:** formatted by `markdown-table-formatter`.
+
+Both tools are installed as dev dependencies in the root `package.json`. See the `radius-markdown-lint` skill for how to run them.
+
+## Conventions not enforced by tooling
+
+- **Do not hard-wrap prose.** Write each paragraph as a single long line. The line-length rule (MD013) is intentionally disabled; manual line breaks create noisy diffs and break reflowing in editors. This applies to all prose — paragraphs, list item text, blockquote content, and image/link alt text. Code blocks and tables are excluded.
+
+## Before committing
+
+Run the Markdown linters (see the `radius-markdown-lint` skill) on the files you changed and fix any reported issues.