Update to markdown.instructions.md and addition of GFM and generic markdown instructions - Fixes #1108#1109
Conversation
- Added new markdown content creation guidelines. - Introduced GitHub Flavored Markdown (GFM) instructions. - Updated CommonMark Markdown instructions with detailed rules. - Removed redundant content from the original markdown instructions.
There was a problem hiding this comment.
Pull request overview
This PR restructures the repository’s Markdown instruction set by separating content-creation guidance from spec-aligned formatting guidance, introducing dedicated CommonMark and GFM instruction files and updating the instructions index accordingly.
Changes:
- Updated
instructions/markdown.instructions.mdto focus on CommonMark (0.31.2) rules and a validation checklist. - Added new instruction files for GFM (
instructions/markdown-gfm.instructions.md) and for legacy/content-creation rules (instructions/markdown-content-creation.instructions.md). - Updated
docs/README.instructions.mdto list the new/repurposed instruction files.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| instructions/markdown.instructions.md | Repurposes the existing Markdown instructions to be CommonMark-spec focused with a validation checklist. |
| instructions/markdown-gfm.instructions.md | Adds GFM-specific formatting/validation guidance as a separate instruction file. |
| instructions/markdown-content-creation.instructions.md | Preserves the prior “content creation” oriented Markdown rules as a dedicated instruction file. |
| docs/README.instructions.md | Registers the new/updated instruction files in the instructions catalog. |
| - **Backslash escapes**: `\` before any ASCII punctuation character renders the literal character. Not recognized in code spans, code blocks, or autolinks. | ||
| - **Entity and numeric character references**: `&`, `{`, `{` — valid HTML5 entities only. Not recognized in code spans or code blocks. Cannot replace structural characters. |
There was a problem hiding this comment.
In the backslash-escapes rule, the inline code currently shows \\ (two backslashes). In Markdown code spans this will render as two backslashes, but the rule is describing a single backslash escape. Use a single backslash character in the code span so the rendered guidance matches the intended syntax.
There was a problem hiding this comment.
False positive. The code on both lines shows a single backslash.
| - **Hard line breaks**: Two+ trailing spaces or `\` before a line ending. Not recognized in code spans or HTML tags. Does not work at end of a block. | ||
| - **Soft line breaks**: A line ending not preceded by two+ spaces or `\`. Rendered as a space in browsers. |
There was a problem hiding this comment.
The hard/soft line break bullets use \\ in inline code for the backslash marker. In Markdown code spans that renders as two backslashes, which is misleading here—these rules refer to a single trailing \ (backslash). Update the inline code to show a single backslash.
There was a problem hiding this comment.
False positive. The code on both lines shows a single backslash.
| - **Link reference definitions**: `[label]: destination "title"`. Case-insensitive label matching. First definition wins for duplicate labels. Cannot interrupt a paragraph. | ||
| - **Paragraphs**: Consecutive non-blank lines not interpretable as other block constructs. Leading spaces up to 3 are stripped. | ||
| - **Blank lines**: Ignored between blocks; determine whether a list is tight or loose. | ||
| - **Tables** *(extension)*: Header row, delimiter row (`---`, `:---:`, `---:`), zero or more data rows. Delimit cells with `|`. Escape literal pipe as `\|`. Header and delimiter must have matching column count. Broken at first blank line or other block-level structure. |
There was a problem hiding this comment.
The tables rule says to escape a literal pipe as \\|, which will render as two backslashes in a Markdown code span. This should display a single backslash escape (\|) so readers copy the correct syntax.
There was a problem hiding this comment.
Comment is a false positive. The file contains | (a single backslash followed by a pipe) inside backticks. In a Markdown code span, backslashes are literal — there is no escape processing inside backticks. So \| renders exactly as |, which is the correct GFM syntax for escaping a pipe in a table cell.
| - **Backslash escapes**: `\` before any ASCII punctuation character renders the literal character. Not recognized in code spans, code blocks, or autolinks. | ||
| - **Entity and numeric character references**: `&`, `{`, `{` — valid HTML5 entities. Not recognized in code spans or code blocks. Cannot replace structural characters. |
There was a problem hiding this comment.
The backslash-escapes bullet currently shows \\ in inline code. In Markdown code spans this renders as two backslashes, but the rule is about a single backslash escape. Use a single backslash in the code span so the rendered output matches the intended syntax.
There was a problem hiding this comment.
False positive. The code on both lines shows a single backslash.
| - **Hard line breaks**: Two+ trailing spaces or `\` before a line ending. Not recognized in code spans or HTML tags. | ||
| - **Soft line breaks**: A line ending not preceded by two+ spaces or `\`. Rendered as a space in browsers. |
There was a problem hiding this comment.
The hard/soft line break bullets use \\ for the backslash marker, which will render as two backslashes in a code span. These rules refer to a single backslash before the line ending—update the inline code to show a single backslash character.
There was a problem hiding this comment.
False positive. The code on both lines shows a single backslash.
|
|
||
| - **Headings**: Use `##` for H2 and `###` for H3. Ensure that headings are used in a hierarchical manner. Recommend restructuring if content includes H4, and more strongly recommend for H5. | ||
| - **Lists**: Use `-` for bullet points and `1.` for numbered lists. Indent nested lists with two spaces. | ||
| - **Code Blocks**: Use triple backticks (`) to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., `csharp). |
There was a problem hiding this comment.
The fenced-code-block guidance has malformed inline code: it refers to “triple backticks ()” and the example “(e.g., csharp)” is missing a closing backtick. Update this line so it correctly shows triple backticks and a properly formatted language identifier example.
| - **Code Blocks**: Use triple backticks (`) to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., `csharp). | |
| - **Code Blocks**: Use triple backticks (```) to create fenced code blocks. Specify the language after the opening backticks for syntax highlighting (e.g., `csharp`). |
- Refine code block formatting instructions in markdown content creation guidelines. - Add detailed HTML block types for GitHub-flavored markdown.
Pull Request Checklist
npm startand verified thatREADME.mdis up to date.Description
The goal of this PR is to standardize and align the markdown instructions to meet industry specs (CommonMark and GFM). The original markdown.instructions.md I submitted was aligned to content creation and should have been named more clearly to indicate that.
Consumers should select either
markdown.instructions.mdormarkdown-gfm.instructions.mdormarkdown-accessibility.instructions.mddepending on their repo needs.markdown-content-creation.instructions.mdis exclusively used for files containing markdown with content frontmatter.Note
The
suggest-awesome-copilot-instructionsskill will look at the content of the instruction and will suggest correctly (the filename isn't important) - so will generally find the right one depending on your use case.This PR fixes #1108 by:
Type of Contribution
Additional Notes
By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.