Markdown Best Practices¶

This document provides a comprehensive guide to writing technical documentation using the GitHub flavored markdown spec. This guide includes examples of how to use various markdown elements to create visually appealing and informative documentation.

Table of Contents¶

• Markdown Horizontal Rule
• HTML Horizontal Rule
• Table with Alignment
  • Multi-Line Table Cells
  • Task Lists
  • Merge Cells
• Progress Bars
• Highlighting
• Underlining
• Keyboard Shortcuts
  • Navigating
  • Editing
• Centered Images
• Horizontally Aligned Images
• Small Images
• Text Boxes
• Text Wrapping
• Inline Links
• Reference Links
• Simple Contact
• Modern Contact with Social Icons
• Contributing Graph

Line Separators¶

Markdown Horizontal Rule¶

section end

---

section end

***

HTML Horizontal Rule¶

<p>section end</p>

<hr>

Lists¶

Things I need to do today: 1. Fix usability problem 2. Clean up the page * Make the headings bigger 2. Push my changes 3. Create code review * Describe my changes * Assign reviewers * Ask for feedback

Tables¶

Table with Alignment¶

| Left Aligned | Centered | Right Aligned |
| :---         | :---:    | ---:          |
| Cell 1       | Cell 2   | Cell 3        |
| Cell 4       | Cell 5   | Cell 6        |

This will render as:

Multi-Line Table Cells¶

| Name | Details |
| ---  | ---     |
| Item1 | This text is on one line |
| Item2 | This item has:<br>- Multiple items<br>- That we want listed separately |

This will render as:

Task Lists¶

| header 1 | header 2 |
| ---      | ---      |
| cell 1   | cell 2   |
| cell 3   | <ul><li> - [ ] Task one </li><li> - [ ] Task two </li></ul> |

This will render as:

Merge Cells¶

<table>
  <tr>
    <td colspan="2">I take up two columns!</td>
  </tr>
  <tr>
    <td>First column</td>
    <td>Second column</td>
  </tr>
</table>

This will render as:

Text Styling & Formatting¶

• strikethrough or strikethrough
• H₂O is a liquid and C₆H₁₂O₆ is a sugar.
• 19^th
• X² + Y² = Z²
• z² + c
•  
   Install 
   

Progress Bars¶

22%

48%

77%

Highlighting¶

highlighted text.

Underlining¶

I'm Underlined!

Buttons & Keyboard Shortcuts¶

Big Fat Button

Keyboard Shortcuts¶

Press Enter to go to the next page.

Navigating¶

You can navigate through your items or search results using the keyboard. You can use Tab to cycle through results, and Shift + Tab to go backwards. Or use the arrow keys, ↑, →, ↓ and ←.

To copy the selected text, press Ctrl + C.

Editing¶

Press Ctrl + S to save your changes. Select text and press Ctrl + B to make it bold.

Math Equations¶

Images¶

Simple Icons¶

Docker¶

Docker ¶

Centered Images¶

Horizontally Aligned Images¶

Small Images¶

Code documentation - Generated directory tree structure and summaries of the key files in your codebase.

Spike documentation - Generated directory tree structure and summaries of the key files in your codebase.

Chunking documentation - Generated directory tree structure and summaries of the key files in your codebase.

Text Boxes¶

This is text in the box. Much wow

Text Wrapping¶

At the 2019 rendition of E3, an eccentric gamer in attendance interrupted Keanu Reeves' presentation of the role-playing game (RPG) Cyberpunk 2077, loudly claiming, “"You're breathtaking,"” which was directed at the actor-cum-presenter. The image macro used to build the "You're Breathtaking" meme generally features a still of Keanu Reeves pointing at someone in the audience in front of him - that someone is Peter Sark, though there are no images from Keanu's point of view that have since been used as part of the "You're Breathtaking" meme.

Mermaid Diagrams¶

• Mermaid Live Editor

graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;

graph TB

  SubGraph1 --> SubGraph1Flow
  subgraph "SubGraph 1 Flow"
  SubGraph1Flow(SubNode 1)
  SubGraph1Flow -- Choice1 --> DoChoice1
  SubGraph1Flow -- Choice2 --> DoChoice2
  end

  subgraph "Main Graph"
  Node1[Node 1] --> Node2[Node 2]
  Node2 --> SubGraph1[Jump to SubGraph1]
  SubGraph1 --> FinalThing[Final Thing]
end

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

graph TD
A[FastAPI Application] --> B{HTTP Request}
B --> C{Request Validation}
C -- Valid --> D[Route Handler]
C -- Invalid --> E[RequestValidationError]
D --> F{Route Handler Execution}
F -- Success --> G[Response]
F -- Exception --> H{Exception Handling}
H -- RequestError --> I[request_error_handler]
H -- HTTPException --> J[http_exception_handler]
H -- RequestValidationError --> K[request_validation_error_handler]
H -- Unhandled Exception --> L[Internal Server Error]
I --> M[Custom Error Response]
J --> N[HTTP Exception Response]
K --> O[Validation Error Response]
L --> P[Internal Server Error Response]
M --> Q[Return Response]
N --> Q
O --> Q
P --> Q

Return To Top¶

Return

Return

Return

HTML Spacing Entities¶

Note: The   and   entities may not be supported in all browsers. For the narrow no-break space, there isn't a named HTML entity, so the numeric character reference   is used.

Links¶

Inline Links¶

inline link reference link

Reference Links¶

reference link 2

Contact¶

Simple Contact¶

If you have any questions or comments, feel free to reach out to me! - Email: your-email@example.com - Twitter: @YourHandle

Modern Contact with Social Icons¶

_{For readme-ai issues and feature requests please visit our issues page, or start a discussion!}

Contributing Guidelines¶

Contributing Graph¶

References¶

• github-markdown-tricks

Footnotes¶

Here's a sample sentence with a footnote.[^1]

[^1]: And here's the definition of the footnote.