mirror of
https://github.com/github/awesome-copilot.git
synced 2026-04-12 11:15:56 +00:00
Update to markdown.instructions.md and addition of GFM and generic markdown instructions - Fixes #1108 (#1109)
* CHANGE: Update markdown instructions and add new files - 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. * CHANGE: Update markdown content guidelines - Refine code block formatting instructions in markdown content creation guidelines. - Add detailed HTML block types for GitHub-flavored markdown.
This commit is contained in:
Daniel Scott-Raynsford
committed by
GitHub
GitHub
parent
562185066e
commit
b1537c6d96
54
instructions/markdown-content-creation.instructions.md
Normal file
54
instructions/markdown-content-creation.instructions.md
Normal file
@@ -0,0 +1,54 @@
|
||||
---
|
||||
description: 'Markdown guidelines and content creation standards for blog posts'
|
||||
applyTo: '**/*.md'
|
||||
---
|
||||
|
||||
# Markdown Content Rules
|
||||
|
||||
The following markdown content rules are enforced in the validators:
|
||||
|
||||
1. **Headings**: Use appropriate heading levels (H2, H3, etc.) to structure your content. Do not use an H1 heading, as this will be generated based on the title.
|
||||
2. **Lists**: Use bullet points or numbered lists for lists. Ensure proper indentation and spacing.
|
||||
3. **Code Blocks**: Use fenced code blocks for code snippets. Specify the language for syntax highlighting.
|
||||
4. **Links**: Use proper markdown syntax for links. Ensure that links are valid and accessible.
|
||||
5. **Images**: Use proper markdown syntax for images. Include alt text for accessibility.
|
||||
6. **Tables**: Use markdown tables for tabular data. Ensure proper formatting and alignment.
|
||||
7. **Line Length**: Limit line length to 400 characters for readability.
|
||||
8. **Whitespace**: Use appropriate whitespace to separate sections and improve readability.
|
||||
9. **Front Matter**: Include YAML front matter at the beginning of the file with required metadata fields.
|
||||
|
||||
## Formatting and Structure
|
||||
|
||||
Follow these guidelines for formatting and structuring your markdown content:
|
||||
|
||||
- **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`).
|
||||
- **Links**: Use `[link text](URL)` for links. Ensure that the link text is descriptive and the URL is valid.
|
||||
- **Images**: Use `` for images. Include a brief description of the image in the alt text.
|
||||
- **Tables**: Use `|` to create tables. Ensure that columns are properly aligned and headers are included.
|
||||
- **Line Length**: Break lines at 80 characters to improve readability. Use soft line breaks for long paragraphs.
|
||||
- **Whitespace**: Use blank lines to separate sections and improve readability. Avoid excessive whitespace.
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Ensure compliance with the following validation requirements:
|
||||
|
||||
### Front Matter
|
||||
|
||||
- [ ] `post_title`: The title of the post.
|
||||
- [ ] `author1`: The primary author of the post.
|
||||
- [ ] `post_slug`: The URL slug for the post.
|
||||
- [ ] `microsoft_alias`: The Microsoft alias of the author.
|
||||
- [ ] `featured_image`: The URL of the featured image.
|
||||
- [ ] `categories`: The categories for the post. These categories must be from the list in /categories.txt.
|
||||
- [ ] `tags`: The tags for the post.
|
||||
- [ ] `ai_note`: Indicate if AI was used in the creation of the post.
|
||||
- [ ] `summary`: A brief summary of the post. Recommend a summary based on the content when possible.
|
||||
- [ ] `post_date`: The publication date of the post.
|
||||
|
||||
### Content and Formatting
|
||||
|
||||
- [ ] Content follows the markdown content rules specified above.
|
||||
- [ ] Content is properly formatted and structured according to the guidelines.
|
||||
- [ ] Validation tools have been run to check for compliance with the rules and guidelines.
|
||||
68
instructions/markdown-gfm.instructions.md
Normal file
68
instructions/markdown-gfm.instructions.md
Normal file
@@ -0,0 +1,68 @@
|
||||
---
|
||||
description: 'Markdown formatting for GitHub-flavored markdown (GFM) files'
|
||||
applyTo: '**/*.md'
|
||||
---
|
||||
|
||||
# GitHub Flavored Markdown (GFM)
|
||||
|
||||
Apply these rules per the [GFM spec](https://github.github.com/gfm/) when writing or reviewing `.md` files. GFM is a strict superset of CommonMark. GFM spec for reference only. Do not download GFM Spec.
|
||||
|
||||
## Preliminaries
|
||||
|
||||
- A line ends at a newline (`U+000A`), carriage return (`U+000D`), or end of file. A blank line contains only spaces or tabs.
|
||||
- Tabs behave as 4-space tab stops for block structure but are not expanded in content.
|
||||
- Replace `U+0000` with the replacement character `U+FFFD`.
|
||||
|
||||
## Leaf Blocks
|
||||
|
||||
- **Thematic breaks**: 3+ matching `-`, `_`, or `*` characters on a line with 0–3 spaces indent. No other characters on the line. Can interrupt a paragraph.
|
||||
- **ATX headings**: 1–6 `#` characters followed by a space or end of line. Optional closing `#` sequence (preceded by a space). 0–3 spaces indent allowed.
|
||||
- **Setext headings**: Text underlined with `=` (level 1) or `-` (level 2). Cannot interrupt a paragraph — blank line required after a preceding paragraph.
|
||||
- **Indented code blocks**: Lines indented 4+ spaces. Cannot interrupt a paragraph. Content is literal text, not parsed as Markdown.
|
||||
- **Fenced code blocks**: Open with 3+ backticks or tildes (do not mix). Closing fence must use same character with at least the same count. Specify language identifier after the opening fence. Content is literal text.
|
||||
- **HTML blocks**: Seven types defined by start/end tag conditions. Types 1–6 can interrupt paragraphs; type 7 cannot. Content is passed through as raw HTML.
|
||||
- Type 1: `<script>`, `<pre>`, or `<style>` (case-insensitive) — ends at matching closing tag.
|
||||
- Type 2: `<!--` comment — ends at `-->`.
|
||||
- Type 3: `<?` processing instruction — ends at `?>`.
|
||||
- Type 4: `<!` + uppercase letter (e.g., `<!DOCTYPE>`) — ends at `>`.
|
||||
- Type 5: `<![CDATA[` — ends at `]]>`.
|
||||
- Type 6: Block-level HTML tags (`<div>`, `<table>`, `<p>`, `<h1>`–`<h6>`, `<ul>`, `<ol>`, `<section>`, etc.) — ends at a blank line.
|
||||
- Type 7: Any other complete open or closing tag on its own line — ends at a blank line. Cannot interrupt a paragraph.
|
||||
- **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.
|
||||
|
||||
## Container Blocks
|
||||
|
||||
- **Block quotes**: Lines prefixed with `>` (optionally followed by a space). Lazy continuation allowed for paragraph text only. A blank line separates consecutive block quotes.
|
||||
- **List items**: Bullet markers (`-`, `+`, `*`) or ordered markers (1–9 digits + `.` or `)`). Content column determined by marker width + spaces to first non-whitespace. Sublists must be indented to the content column. An ordered list interrupting a paragraph must start with `1`.
|
||||
- **Task list items** *(extension)*: `- [ ]` (unchecked) or `- [x]` (checked) at the start of a list item paragraph. Space between `-` and `[` is required. May be nested.
|
||||
- **Lists**: Sequence of same-type list items. Changing bullet character or ordered delimiter starts a new list. A list is loose if any item is separated by a blank line.
|
||||
|
||||
## Inlines
|
||||
|
||||
- **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.
|
||||
- **Code spans**: Backtick-delimited inline code. Line endings convert to spaces. Leading and trailing space stripped when both present. Backslash escapes are literal inside code spans.
|
||||
- **Emphasis and strong emphasis**: `*`/`_` for `<em>`, `**`/`__` for `<strong>`. `_` is not allowed for intraword emphasis. Left-flanking / right-flanking delimiter run rules apply. Delimiter run length sum must not be a multiple of 3 when one delimiter can both open and close (unless both lengths are multiples of 3).
|
||||
- **Strikethrough** *(extension)*: `~~text~~` — one or two tildes. Does not span across paragraphs. Three or more tildes do not create strikethrough.
|
||||
- **Links**: Inline `[text](url "title")` or reference `[text][label]` / `[text][]` / `[text]`. Link text may contain inlines but not other links. Destination in `<…>` allows spaces. No whitespace between link text and `(` or `[`.
|
||||
- **Images**: `` — same syntax as links prefixed with `!`. Alt text is the plain-string content of the description.
|
||||
- **Autolinks**: `<URI>` or `<email>` in angle brackets. Scheme must be 2–32 characters starting with an ASCII letter.
|
||||
- **Autolinks** *(extension)*: Bare `http://`, `https://`, `www.` URLs and bare email addresses auto-link without angle brackets. Trailing punctuation excluded; parentheses balanced.
|
||||
- **Raw HTML**: Open/close tags, comments (`<!-- -->`), processing instructions (`<? ?>`), declarations (`<!…>`), CDATA (`<![CDATA[…]]>`) are passed through.
|
||||
- **Disallowed raw HTML** *(extension)*: `<title>`, `<textarea>`, `<style>`, `<xmp>`, `<iframe>`, `<noembed>`, `<noframes>`, `<script>`, `<plaintext>` have their leading `<` replaced with `<`.
|
||||
- **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.
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] ATX headings use 1–6 `#` followed by a space.
|
||||
- [ ] Fenced code blocks specify a language identifier and use matching fence characters and counts.
|
||||
- [ ] Tables include header and delimiter rows with matching column count. Alignment set with `:` in the delimiter.
|
||||
- [ ] Task list items have a space between `-` and `[ ]` or `[x]`.
|
||||
- [ ] Emphasis uses `*` for intraword; `_` only at word boundaries.
|
||||
- [ ] Strikethrough uses exactly `~~` (not 3+ tildes).
|
||||
- [ ] Links use `[text](url)` or reference syntax with no whitespace before `(` or `[`.
|
||||
- [ ] No disallowed raw HTML tags (`<script>`, `<style>`, `<title>`, `<textarea>`, `<xmp>`, `<iframe>`, `<noembed>`, `<noframes>`, `<plaintext>`).
|
||||
@@ -1,52 +1,58 @@
|
||||
---
|
||||
description: 'Documentation and content creation standards'
|
||||
description: 'Markdown formatting aligned to the CommonMark specification (0.31.2)'
|
||||
applyTo: '**/*.md'
|
||||
---
|
||||
|
||||
## Markdown Content Rules
|
||||
# CommonMark Markdown
|
||||
|
||||
The following markdown content rules are enforced in the validators:
|
||||
Apply these rules per the [CommonMark spec 0.31.2](https://spec.commonmark.org/0.31.2/) when writing or reviewing `.md` files. CommonMark spec for reference only. Do not download CommonMark spec.
|
||||
|
||||
1. **Headings**: Use appropriate heading levels (H2, H3, etc.) to structure your content. Do not use an H1 heading, as this will be generated based on the title.
|
||||
2. **Lists**: Use bullet points or numbered lists for lists. Ensure proper indentation and spacing.
|
||||
3. **Code Blocks**: Use fenced code blocks for code snippets. Specify the language for syntax highlighting.
|
||||
4. **Links**: Use proper markdown syntax for links. Ensure that links are valid and accessible.
|
||||
5. **Images**: Use proper markdown syntax for images. Include alt text for accessibility.
|
||||
6. **Tables**: Use markdown tables for tabular data. Ensure proper formatting and alignment.
|
||||
7. **Line Length**: Limit line length to 400 characters for readability.
|
||||
8. **Whitespace**: Use appropriate whitespace to separate sections and improve readability.
|
||||
9. **Front Matter**: Include YAML front matter at the beginning of the file with required metadata fields.
|
||||
## Preliminaries
|
||||
|
||||
## Formatting and Structure
|
||||
- A line ends at a newline (`U+000A`), carriage return (`U+000D`), or end of file. A blank line contains only spaces or tabs.
|
||||
- Tabs behave as 4-space tab stops for block structure but are not expanded in content.
|
||||
- Replace `U+0000` with the replacement character `U+FFFD`.
|
||||
- **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.
|
||||
|
||||
Follow these guidelines for formatting and structuring your markdown content:
|
||||
## Leaf Blocks
|
||||
|
||||
- **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).
|
||||
- **Links**: Use `[link text](URL)` for links. Ensure that the link text is descriptive and the URL is valid.
|
||||
- **Images**: Use `` for images. Include a brief description of the image in the alt text.
|
||||
- **Tables**: Use `|` to create tables. Ensure that columns are properly aligned and headers are included.
|
||||
- **Line Length**: Break lines at 80 characters to improve readability. Use soft line breaks for long paragraphs.
|
||||
- **Whitespace**: Use blank lines to separate sections and improve readability. Avoid excessive whitespace.
|
||||
- **Thematic breaks**: 3+ matching `-`, `_`, or `*` characters on a line with 0–3 spaces indent. Only spaces or tabs allowed on the line otherwise. Can interrupt a paragraph.
|
||||
- **ATX headings**: 1–6 `#` characters followed by a space or end of line. Optional closing `#` sequence (preceded by a space). 0–3 spaces indent allowed.
|
||||
- **Setext headings**: Text underlined with `=` (level 1) or `-` (level 2). Cannot interrupt a paragraph — blank line required after a preceding paragraph.
|
||||
- **Indented code blocks**: Lines indented 4+ spaces. Cannot interrupt a paragraph. Content is literal text, not parsed as Markdown.
|
||||
- **Fenced code blocks**: Open with 3+ backticks or tildes (do not mix). Closing fence must use same character with at least the same count. Info string after backtick fence cannot contain backticks. Specify language identifier after the opening fence. Content is literal text.
|
||||
- **HTML blocks**: Seven types defined by start/end tag conditions. Types 1–5 end at their matching end pattern. Type 6 ends at a blank line. Type 7 cannot interrupt a paragraph and ends at a blank line.
|
||||
- **Link reference definitions**: `[label]: destination "title"`. Case-insensitive label matching (Unicode case fold). 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.
|
||||
|
||||
## Validation Requirements
|
||||
## Container Blocks
|
||||
|
||||
Ensure compliance with the following validation requirements:
|
||||
- **Block quotes**: Lines prefixed with `>` (optionally followed by a space). Lazy continuation allowed for paragraph text only. A blank line separates consecutive block quotes.
|
||||
- **List items**: Bullet markers (`-`, `+`, `*`) or ordered markers (1–9 digits + `.` or `)`). Content column determined by marker width + spaces to first non-whitespace (1–4 spaces after marker). Sublists must be indented to the content column. An ordered list interrupting a paragraph must start with `1`.
|
||||
- **Lists**: Sequence of same-type list items. Changing bullet character or ordered delimiter starts a new list. A list is loose if any item is separated by a blank line.
|
||||
|
||||
- **Front Matter**: Include the following fields in the YAML front matter:
|
||||
## Inlines
|
||||
|
||||
- `post_title`: The title of the post.
|
||||
- `author1`: The primary author of the post.
|
||||
- `post_slug`: The URL slug for the post.
|
||||
- `microsoft_alias`: The Microsoft alias of the author.
|
||||
- `featured_image`: The URL of the featured image.
|
||||
- `categories`: The categories for the post. These categories must be from the list in /categories.txt.
|
||||
- `tags`: The tags for the post.
|
||||
- `ai_note`: Indicate if AI was used in the creation of the post.
|
||||
- `summary`: A brief summary of the post. Recommend a summary based on the content when possible.
|
||||
- `post_date`: The publication date of the post.
|
||||
- **Code spans**: Backtick-delimited inline code. Line endings convert to spaces. Leading and trailing space stripped when both present (unless content is all spaces). Backslash escapes are literal inside code spans.
|
||||
- **Emphasis and strong emphasis**: `*`/`_` for `<em>`, `**`/`__` for `<strong>`. `_` is not allowed for intraword emphasis. Left-flanking / right-flanking delimiter run rules apply. Delimiter run length sum must not be a multiple of 3 when one delimiter can both open and close (unless both lengths are multiples of 3).
|
||||
- **Links**: Inline `[text](url "title")` or reference `[text][label]` / `[text][]` / `[text]`. Link text may contain inlines but not other links. Destination in `<…>` allows spaces; without angle brackets, balanced parentheses allowed. No whitespace between link text and `(` or `[`.
|
||||
- **Images**: `` — same syntax as links prefixed with `!`. Alt text is the plain-string content of the description.
|
||||
- **Autolinks**: `<URI>` or `<email>` in angle brackets. Scheme must be 2–32 characters starting with an ASCII letter. Bare URLs are not auto-linked in CommonMark (requires angle brackets).
|
||||
- **Raw HTML**: Open/close tags, comments (`<!--` … `-->`), processing instructions (`<?` … `?>`), declarations (`<!` … `>`), CDATA (`<![CDATA[` … `]]>`) are passed through as literal HTML.
|
||||
- **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.
|
||||
|
||||
- **Content Rules**: Ensure that the content follows the markdown content rules specified above.
|
||||
- **Formatting**: Ensure that the content is properly formatted and structured according to the guidelines.
|
||||
- **Validation**: Run the validation tools to check for compliance with the rules and guidelines.
|
||||
## Validation Checklist
|
||||
|
||||
- [ ] ATX headings use 1–6 `#` followed by a space.
|
||||
- [ ] Fenced code blocks specify a language identifier and use matching fence characters and counts.
|
||||
- [ ] Backtick fence info strings do not contain backtick characters.
|
||||
- [ ] Indented code blocks are preceded by a blank line (they cannot interrupt a paragraph).
|
||||
- [ ] Emphasis uses `*` for intraword; `_` only at word boundaries.
|
||||
- [ ] Links use `[text](url)` or reference syntax with no whitespace before `(` or `[`.
|
||||
- [ ] Images include non-empty alt text.
|
||||
- [ ] Autolinks use angle brackets (`<URL>`); bare URLs are not CommonMark autolinks.
|
||||
- [ ] No unbalanced parentheses in bare link destinations (use `<…>` or escape).
|
||||
- [ ] HTML block type 7 (custom/inline-level tags) is preceded by a blank line when following a paragraph.
|
||||
|
||||
Reference in New Issue
Block a user