Copilot Instructions for Markdown Document

copilot-insructions-markdown.md

applyTo	description
**/*.md	Guidelines for technical writing in Markdown, enforcing prettier and markdownlint standards.

MARKDOWN DOCUMENTATION GUIDELINES

When creating or editing Markdown (.md) files, you are acting as a technical writer and editor. Adhere strictly to the following guidelines to ensure consistency, readability, and maintainability of the documentation.

1. Core Principles

• Clarity and Conciseness: Write in clear, simple language. Avoid jargon where possible, or explain it if necessary. Get to the point quickly.
• Consistency: Maintain a consistent tone, terminology, and formatting style across all documents.
• Single Source of Truth: Ensure that the information is accurate and up-to-date. Avoid duplicating information that exists elsewhere; link to it instead.

2. Formatting and Linting (MANDATORY)

This project uses prettier for formatting and markdownlint-cli2 for linting. All your suggestions and generated content MUST conform to the rules enforced by these tools.

• Prettier Compliance:
  • All Markdown output MUST be formatted as if prettier has been run on it.
  • This includes rules for line wrapping, list indentation, table formatting, and spacing.
  • Do not manually break lines within a paragraph; let Prettier handle it. Your primary focus should be on the content, not manual formatting.
• Markdownlint Compliance:
  • Adhere to common markdownlint rules. While you don't need to know every rule, follow these key principles:
    • Headings:
      • Headings must increment by one level at a time (e.g., # -> ## -> ###). Do not skip levels (e.g., # -> ###). (MD001)
      • The first heading in a document should be a level 1 heading (#). (MD041)
    • Code Blocks:
      • Always specify the language for fenced code blocks for syntax highlighting (e.g., ```javascript, ```bash, ```json). Do not use ```text for code. (MD040)
    • Links/Images:
      • Provide descriptive alt text for all images (![alt text for accessibility](path/to/image.png)). (MD045)

3. Document Structure

• Title: Every document must start with a single level 1 heading (# Title), which serves as the document's main title.
• Table of Contents (ToC): For longer documents, consider adding a Table of Contents after the main title to improve navigation.
• Sections: Use headings (##, ###, etc.) to break the document into logical, hierarchical sections. Use whitespace (blank lines) to separate paragraphs and distinct elements for better readability.

4. Content Style

• Emphasis:
  • Use **bold** for strong emphasis (e.g., UI elements, important warnings).
  • Use `code` for inline code, commands, filenames, or technical terms.
  • Use *italic* for mild emphasis or defining terms.
• Links:
  • Use meaningful link text. Instead of "click here," write "see the Installation Guide for details."
  • Prefer relative links for content within this repository.
• Tables:
  • Use tables to present structured data.
  • Ensure tables are correctly structured with headers. Prettier will handle the alignment and padding, but your initial structure must be valid.

5. Specific Elements

• Blockquotes: Use > for quoting text from other sources. They can also be used to highlight notes, tips, or warnings using bold text.
• Task Lists: Use task lists for checklists or tracking to-do items.

6. Avoid

• Raw HTML: Avoid using raw HTML in place of standard Markdown syntax unless absolutely necessary for a feature Markdown doesn't support (e.g., complex tables, specific styling).
• Inconsistent Heading Levels: Do not create a disorganized document structure by using heading levels incorrectly.
• Vague Link Text: Avoid link text like "here," "this," or "link." Make the link text descriptive of its destination.