Skip to content

Commit c5d1dd6

Browse files
simonkurtz-MSFTsimonkurtz-MSFT
committed
Add markdown instructions
1 parent ad92280 commit c5d1dd6

2 files changed

Lines changed: 234 additions & 2 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -444,6 +444,7 @@ When designing or restructuring a sample notebook:
444444
- Python: see `.github/python.instructions.md`
445445
- Bicep: see `.github/bicep.instructions.md`
446446
- JSON: see `.github/json.instructions.md`
447+
- Markdown: see `.github/markdown.instructions.md`
447448

448449
## Formatting and Style
449450

@@ -455,8 +456,8 @@ When designing or restructuring a sample notebook:
455456
- Only use apostrophe (U+0027) and quotes (U+0022), not left or right single or double quotation marks.
456457
- Use only ASCII punctuation in text content. Replace em-dashes (U+2014) and en-dashes (U+2013) with a plain hyphen-minus (`-`), the minus sign (U+2212) with `-`, the horizontal ellipsis (U+2026) with `...`, and math comparison glyphs (U+2264, U+2265, U+2260) with `<=`, `>=`, `!=`. These typographic characters do not always render correctly in downstream surfaces such as Azure Monitor Workbook markdown tiles, slide-deck HTML, and some terminal fonts. This rule applies to every text-bearing file in the repository, including Markdown, Python docstrings/comments, Bicep `@description` strings, XML policy comments, and **JSON string values that contain user-facing text (notably Azure Monitor Workbook `*.workbook.json` files where markdown is embedded in `content.json` strings).**
457458
- Do not localize URLs (e.g. no "en-us" in links).
458-
- Never use emoji variation selectors in Markdown. They are sneaky little things that can cause rendering and Markdown anchor link issues.
459-
- **Markdown tables must be column-aligned.** Pad cell values with spaces so that every `|` delimiter in a column lines up vertically. Use the separator row (`---`, `:---:`, etc.) to establish column widths and align all subsequent rows to match. This applies to every Markdown file in the repository (READMEs, skills, instructions, etc.).
459+
460+
For Markdown-specific formatting guidelines (including critical rules about emoji variation selectors and table alignment), see `.github/markdown.instructions.md`.
460461

461462
## Testing and Edge Cases
462463

‎.github/markdown.instructions.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
applyTo: "**/*.md"
3+
---
4+
5+
# Markdown Guidelines
6+
7+
This document provides standards for Markdown files in the APIM Samples repository, including README files, documentation, instructions, and skill guides.
8+
9+
## Critical Rules
10+
11+
### 🚨 No Emoji Variation Selectors in Markdown Links
12+
13+
**This is the most important rule.** Emoji variation selectors cause rendering and Markdown anchor link failures.
14+
15+
❌ **WRONG** — DO NOT DO THIS:
16+
```markdown
17+
## ✅ Prerequisites
18+
19+
[Go to Prerequisites](#%EF%B8%8F-prerequisites) <!-- Encoded emoji in link -->
20+
```
21+
22+
✅ **CORRECT** — DO THIS:
23+
```markdown
24+
## ✅ Prerequisites
25+
26+
[Go to Prerequisites](#prerequisites) <!-- Text only, no emoji encoding -->
27+
```
28+
29+
**Why:** When you create an anchor link with an emoji in the heading, Markdown renders the emoji but the anchor reference gets URL-encoded (like `%EF%B8%8F`). The link then breaks because the actual anchor is just the text portion without the encoding.
30+
31+
**The pattern:**
32+
- **Keep emojis in headings** for visual clarity — they're fine there
33+
- **Never include emojis in anchor link references** — always reference just the text
34+
- **When linking to a heading**, use only the text: `[Link text](#heading-text-only)`
35+
36+
---
37+
38+
## Formatting Standards
39+
40+
### Line Endings
41+
- Use **LF line endings only**, never CRLF
42+
- This applies to all files, including Windows development environments
43+
44+
### Quotes and Apostrophes
45+
- Use only straight quotes and apostrophes: `'` (U+0027) and `"` (U+0022)
46+
- Never use typographic/curly quotes: `'` `'` `"` `"`
47+
- Improves consistency across editors and platforms
48+
49+
### Markdown Tables
50+
**Markdown tables must be column-aligned.** Pad cell values with spaces so that every `|` delimiter in a column lines up vertically.
51+
52+
❌ **WRONG** — misaligned columns:
53+
```markdown
54+
| Name | Value |
55+
|---|---|
56+
| Short | 123 |
57+
| Very Long Name | 45 |
58+
```
59+
60+
✅ **CORRECT** — aligned columns:
61+
```markdown
62+
| Name | Value |
63+
| --- | --- |
64+
| Short | 123 |
65+
| Very Long Name | 45 |
66+
```
67+
68+
Use the separator row (`---`, `:---:`, `---:`, etc.) to establish column widths, then align all subsequent rows to match.
69+
70+
### File Links
71+
72+
When referencing files or line numbers in documentation:
73+
74+
**Format:** `[display text](path/to/file.md)` or `[display text](path/to/file.md#L10)` for specific lines
75+
76+
**Rules:**
77+
- Display text must match or describe the target
78+
- Use workspace-relative paths (no `file://` or `vscode://` schemes)
79+
- Encode spaces in the URL: `My File.md` → `My%20File.md`
80+
- Line numbers are 1-indexed: `#L10` (not `#L9`)
81+
- For line ranges: `#L10-L12`
82+
- Do NOT wrap file paths in backticks — they're already links
83+
84+
✅ **CORRECT:**
85+
```markdown
86+
See [configuration guide](docs/configuration.md) for details.
87+
88+
The [initialization code](src/init.ts#L15-L20) runs on startup.
89+
90+
Update [my config file](path/to/My%20Config.md) as needed.
91+
```
92+
93+
❌ **WRONG:**
94+
```markdown
95+
See `docs/configuration.md` for details.
96+
97+
The `src/init.ts` runs on startup.
98+
99+
See the `README.md#L10` file.
100+
```
101+
102+
### Symbols and Code References
103+
104+
- Wrap symbol names in backticks: `functionName()`, `ClassName`, `variableName`
105+
- Use for methods, classes, properties, types, and identifiers
106+
- Do NOT wrap file paths or headings in backticks
107+
108+
---
109+
110+
## Repository File Conventions
111+
112+
### README Files
113+
114+
**Location & Naming:**
115+
- Root `README.md` - Main repository overview
116+
- `infrastructure/[name]/README.md` - Infrastructure architecture guide
117+
- `samples/[name]/README.md` - Sample documentation
118+
- `shared/` folders - Optional READMEs for component overview
119+
120+
**Structure** (see `copilot-instructions.md` for detailed layouts):
121+
- Consistent heading hierarchy and emoji usage across similar documents
122+
- Badges for runtime, supported services, prerequisites
123+
- Clear sections: Objectives, Scenario, Lab Components, Configuration, Results, Clean Up, Links
124+
- Consistent ordering makes all READMEs feel familiar
125+
126+
### Instruction Files
127+
128+
**Location & Naming:**
129+
- Language-specific: `.github/[language].instructions.md` (e.g., `python.instructions.md`, `markdown.instructions.md`)
130+
- Topic-specific: `.github/markdown.instructions.md` (e.g., for Markdown formatting)
131+
- General: `.github/copilot-instructions.md`
132+
133+
**Metadata Block:**
134+
```markdown
135+
---
136+
applyTo: "**/*.md"
137+
---
138+
```
139+
140+
- `applyTo` uses glob patterns to scope where the instruction applies
141+
- `**` matches any folder depth
142+
- Examples: `**/*.py`, `**/*.bicep`, `.github/workflows/*.yml`
143+
144+
### Skill Files
145+
146+
Location: `.github/skills/[skill-name]/SKILL.md`
147+
148+
Structured guides for domain-specific tasks (Bicep, Python policies, sample creation, etc.).
149+
150+
---
151+
152+
## When to Use Markdown Files
153+
154+
| File Type | When | Example |
155+
| --- | --- | --- |
156+
| README | Document a folder/project | `infrastructure/simple-apim/README.md` |
157+
| CONTRIBUTING | Contribution process | Root `CONTRIBUTING.md` |
158+
| Instructions | Copilot guidance | `.github/bicep.instructions.md` |
159+
| Skill Guide | Domain expertise | `.github/skills/sample-creator/SKILL.md` |
160+
| Index/Navigation | Landing pages, TOCs | `samples/README.md` listing all samples |
161+
162+
---
163+
164+
## Documentation Best Practices
165+
166+
### Headings
167+
168+
- Use consistent emoji patterns across related documents (e.g., all README files use the same emoji set)
169+
- Heading levels should reflect document structure (H1 for title, H2 for major sections)
170+
- Never skip levels (e.g., H1 → H3, skipping H2)
171+
172+
### Lists
173+
174+
- Use bullet lists for unordered items
175+
- Use numbered lists for ordered steps or priorities
176+
- Indent sub-items consistently
177+
- Keep list items concise (one line when possible)
178+
179+
### Emphasis
180+
181+
- Use `**bold**` for emphasis and strong concepts
182+
- Use `*italic*` for variables or placeholders
183+
- Use `code` (backticks) for symbols, filenames, and technical terms
184+
- Use blockquotes `>` for notes, tips, and callouts
185+
186+
### Cross-References
187+
188+
- Use reference-style links at the bottom for multiple references to the same target
189+
- Example:
190+
```markdown
191+
See the [setup guide][setup] and [troubleshooting][troubleshooting] pages.
192+
193+
[setup]: docs/setup.md
194+
[troubleshooting]: docs/troubleshooting.md
195+
```
196+
197+
- Link within README sections using anchor links: `[Jump to section](#section-name)`
198+
199+
---
200+
201+
## Accessibility
202+
203+
### Contrast and Color
204+
205+
- Do NOT rely on color alone to convey meaning (applies to embedded diagrams and exported slides)
206+
- Pair color cues with labels, text, icons, or structure
207+
- Ensure text meets WCAG 2.0 AA contrast: `4.5:1` for normal text, `3:1` for large text
208+
209+
### Images and Alt Text
210+
211+
- Provide meaningful `alt` text for all images and diagrams
212+
- Alt text should describe the image purpose, not just say "screenshot" or "diagram"
213+
- Example: `![Deployment workflow showing resource dependencies](images/deployment.png)`
214+
215+
### Code Blocks
216+
217+
- Use language tags for syntax highlighting: ` ```python `, ` ```bicep `, ` ```json `
218+
- Include enough context in code examples that they're self-explanatory
219+
220+
---
221+
222+
## Common Issues and Fixes
223+
224+
| Issue | Cause | Fix |
225+
| --- | --- | --- |
226+
| Anchor links break | Emoji in heading + encoded in link | Remove emoji from link reference: `[text](#heading-only)` |
227+
| Tables misaligned | Inconsistent column widths | Pad cells with spaces to align `\|` delimiters |
228+
| File links broken | Wrong path or encoded characters | Use relative paths, encode spaces: `My%20File.md` |
229+
| Symbols not highlighted | Missing backticks | Wrap in backticks: `symbolName` |
230+
| Line ending issues | Mixed CRLF/LF | Ensure all `.md` files use LF only |
231+
| Rendering issues | Curly quotes | Use straight quotes: `'` and `"` only |

0 commit comments

Comments
 (0)