markdown-documentation

Structure the README with a clear heading hierarchy, a table of contents for long documents, code blocks with language specification, and descriptive links. Add badges for build status and version, and include alt text on all images for accessibility.

Create tables using pipe characters to separate columns and a header separator row of dashes. You can control alignment with colons: left-aligned with :---, centered with :---:, and right-aligned with ---:.

Yes, GitHub Markdown supports collapsible sections using the HTML details and summary tags. Content inside the details element is hidden until clicked, and it can contain lists, code blocks, and images.

Use GitHub-style alert syntax with blockquotes: > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], or > [!CAUTION]. These render as highlighted callout boxes on GitHub to draw attention to key information.

Yes, GitHub renders Mermaid diagrams inside fenced code blocks tagged with the mermaid language. You can create flowcharts, sequence diagrams, and other visualizations directly in Markdown without external images.

Common mistakes include using 'click here' as link text, omitting alt text on images, skipping language specification in code blocks, mixing HTML and Markdown unnecessarily, and creating walls of text without headings or breaks.