Skip to content

1001-markdown.md

Latest commit

 

History

History
148 lines (99 loc) · 2.85 KB

1001-markdown.md

File metadata and controls

148 lines (99 loc) · 2.85 KB
Error in user YAML: (<unknown>): did not find expected alphabetic or numeric character while scanning an alias at line 2 column 8
---
description: Always use for writing or updating Markdown files to ensure consistent formatting and readability across documentation
globs: **/*.{md,mdx}
alwaysApply: false
---

Markdown Documentation Standards

blefnk/rules 1.0.0

Context

  • Applies to all .md and .mdx files.
  • Ensures clear, structured, and consistent formatting.

Requirements

  • Follow the Markdown Guide for syntax.
  • Maintain logical document structure and readability.
  • Use minimal, structured YAML front matter when needed.
  • Leverage Mermaid diagrams for complex visual documentation.

Markdown Formatting Rules

  • Use ATX-style headings (# Heading), maintaining a proper hierarchy (max depth: 4).
  • Add a blank line before and after headings.
  • Indent XML tag content by 2 spaces; close tags on a new line.
  • Use blockquotes with emoji for callouts (Warning, Tip, Note).

🚨 Warning: Critical information. 💡 Tip: Helpful suggestion. 📝 Note: Additional context.

Code Blocks

  • Use triple backticks and specify language.
  • Indent properly within blocks.
  • Add a blank line before and after the block.
  • Use inline code for short references.
function example(): void {
  console.log("Hello, Reliverse!");
}

Use example() inline.

Tables

  • Use alignment indicators (:---, :---:, ---:).
  • Include a header row and separator.
  • Keep tables simple, with blank lines before and after.
Name Type Description
id number Primary key
name string User's name

Special Elements

Callouts

Use blockquotes with emoji:

🚨 Warning: Critical information. 💡 Tip: Helpful suggestion. 📝 Note: Additional context.

Mermaid Diagrams

Use Mermaid for architecture flows, decision trees, state machines, and AI agent rule flows.

Diagram Best Practices

  1. Add a title (--- title: Example ---).
  2. Use descriptive node labels.
  3. Comment complex flows.
  4. Group related components in subgraphs.
  5. Maintain consistent layout (TD, LR, TB).
  6. Keep diagrams focused.
---
title: Example Workflow
---
graph TD
  A[Start] --> B{Decision}
  B -->|Yes| C[Process 1]
  B -->|No| D[Process 2]
  C --> E[End]
  D --> E
Loading 
graph TD
A-->B
B-->C
Loading

❌ No title, unclear labels, no context.

Examples

# Heading  

> 🚨 **Warning:** Important detail.

✅ Proper headings, callouts, and spacing.

❌ No headings. ❌ Inline code block missing triple backticks.