Refine markdown instructions

Author: simonkurtz-MSFT

.github/agents/apim-sample-creator.agent.md

@@ -1,5 +1,6 @@
 ---
 name: APIM Sample Creator
+.
 description: "Use when adding or scaffolding an APIM sample, designing its notebook versus sample-local helper boundary, creating from samples/_TEMPLATE, or updating README, website, slide deck, and compatibility listings."
 tools: [read, search, edit, todo]
 argument-hint: "Describe the sample to add, including its sample name, display name, supported infrastructures, scenario, and any APIs or policies."
@@ -58,7 +59,7 @@ You are the specialist for adding new samples to the APIM Samples repository.
 5. Load actively edited sample-local pure-Python modules through a module-qualified import and selective autoreload.
 6. Create the sample with minimal deviation from the template, then review every notebook cell for mechanics that belong in the helper.
 7. Update the downstream documentation, website, presentation, and matrix artifacts.
-8. Run focused lint/tests followed by the combined repository checks. Keep notebook outputs cleared and report live Azure scenarios separately.
+8. Run markdownlint on all changed Markdown files and require zero violations. Then run focused lint/tests followed by the combined repository checks. Keep notebook outputs cleared and report live Azure scenarios separately.
 9. Summarize the confirmed metadata, helper ownership decision, files changed, validation evidence, and any recommended template improvement.
 
 ## Output Format

.github/agents/apim-sample-publisher.agent.md

@@ -73,15 +73,16 @@ Treat search visibility as a publication criterion, not as optional polish. Revi
    ./tests/python/check_python.sh
    ```
 
-10. Export the self-contained presentation and treat warnings about missing images as failures to investigate:
+10. Run markdownlint on all changed Markdown files and require zero violations. Fix violations instead of disabling rules unless a narrowly scoped suppression is necessary and documented.
+11. Export the self-contained presentation and treat warnings about missing images as failures to investigate:
 
    ```bash
    uv run python setup/export_presentation.py
    ```
 
-11. Run the SEO pass when public website content changed. Parse the inline JSON-LD block and `docs/sitemap.xml`, then verify that structured-data entries and visible cards stay synchronized.
-12. Preview the staged website when website or deck content changed. Use `uv run python setup/serve_website.py` and review both the landing page and `/slide-deck.html`. Check desktop and narrow layouts when visual changes are material.
-13. Inspect the final diff after validation. Do not include generated artifacts such as `build/`, `_site/`, coverage files, or lint reports unless the repository intentionally tracks them.
+12. Run the SEO pass when public website content changed. Parse the inline JSON-LD block and `docs/sitemap.xml`, then verify that structured-data entries and visible cards stay synchronized.
+13. Preview the staged website when website or deck content changed. Use `uv run python setup/serve_website.py` and review both the landing page and `/slide-deck.html`. Check desktop and narrow layouts when visual changes are material.
+14. Inspect the final diff after validation. Do not include generated artifacts such as `build/`, `_site/`, coverage files, or lint reports unless the repository intentionally tracks them.
 
 When live Azure validation is relevant but not requested or not available, report the exact notebook scenario and supported infrastructure combinations that remain to be exercised. Do not substitute unit tests for live scenario evidence.
 

.github/copilot-instructions.md

@@ -502,6 +502,7 @@ Check `docs/README.md` for local preview instructions and styling notes. The pag
 
 ## Required before each commit
 - Ensure all code is well-documented and follows the guidelines in this file.
+- Ensure markdownlint passes with zero violations for all new or modified Markdown files.
 - Ensure that Jupyter notebooks do not contain any cell output.
 - Ensure that Jupyter notebooks have `index` assigned to `1` in the first cell.
 - If the change touches the infrastructure list, sample list, quick-start steps, or architecture SVGs, ensure `docs/index.html` (and the asset copy step in `.github/workflows/github-pages.yml` where relevant) has been updated to match.

.github/markdown.instructions.md

@@ -8,6 +8,12 @@ This document provides standards for Markdown files in the APIM Samples reposito
 
 ## Critical Rules
 
+### Markdownlint Must Pass
+
+- Every new or modified Markdown file must pass markdownlint with zero violations before the work is considered complete.
+- Run markdownlint against all changed `.md` files using the available CLI or VS Code diagnostics.
+- Fix violations instead of disabling rules. Add a narrowly scoped suppression only when the Markdown intentionally cannot comply, and explain why next to the suppression.
+
 ### 🚨 No Emoji Variation Selectors in Markdown Links
 
 **This is the most important rule.** Emoji variation selectors cause rendering and Markdown anchor link failures.
@@ -223,6 +229,7 @@ Structured guides for domain-specific tasks (Bicep, Python policies, sample crea
 
 | Issue | Cause | Fix |
 | --- | --- | --- |
+| Markdownlint failure | Markdown does not meet the configured lint rules | Fix every reported violation and rerun markdownlint |
 | Anchor links break | Emoji in heading + encoded in link | Remove emoji from link reference: `[text](#heading-only)` |
 | Tables misaligned | Inconsistent column widths | Pad cells with spaces to align `\|` delimiters |
 | File links broken | Wrong path or encoded characters | Use relative paths, encode spaces: `My%20File.md` |