Markdown Guide: Syntax, Tables & MDX Tips

Headings & Emphasis

# H1 — one per page (the title)

## H2 — major sections

### H3 — subsections

**bold** for UI labels, _italic_ for terms, ~~strikethrough~~ for diffs.
`inline code` for file names like `astro.config.mjs`.

Keep a blank line around headings and lists — most renderers require it.

Links & Images

[Relative link](/cheatsheets/git-commands/)
[External with title](https://astro.build "Astro docs")
![Alt text describes the image](/og-ivyivy-default.png)
[![Badge](https://img.shields.io/badge/build-passing-brightgreen)](https://ivyivy.com)

SEO tip: never use “click here” as link text. Use descriptive anchors like “Git commands cheatsheet”.

Lists & Tasks

- Unordered item
  - Nested with 2 spaces

1. Ordered step
2. Next step

- [x] Ship cheatsheet
- [ ] Add OG image

Tables That Render Everywhere

| Tool     | License | In-browser? |
| -------- | ------- | ----------- |
| Prettier | MIT     | Via plugins |
| ESLint   | MIT     | Playground  |

Alignment	Syntax	Use for
Left	:---	Text
Center	:---:	Status
Right	---:	Numbers

Keep tables under 5 columns — on mobile they scroll horizontally and wide tables get abandoned.

Code Blocks

```js title="hello.js"
export function hello(name = "IvyIvy") {
  return `Hello, ${name}!`;
}
```

Short inline references (npm run build) beat full blocks for single commands.

Quotes, Callouts & Footnotes

> Blockquote for key takeaways and warnings.

GitHub callouts:

> [!NOTE]
> Mermaid diagrams render on GitHub but not everywhere — keep a text fallback.

Footnote example[^1].

[^1]: Footnotes work on GitHub, Astro, Docusaurus, and most MDX setups.

MDX Tips (Astro / Docusaurus)

import AdSlot from "../../components/AdSlot.astro";

## Section with a component

<AdSlot slotId="docs-middle" />

| Prop     | Type     | Default |
| -------- | -------- | ------- |
| `slotId` | `string` | —       |

Rules that save hours:

1. Components must start with a capital letter or contain a dot.
2. Curly braces in code samples must be escaped or wrapped in a code block.
3. Frontmatter (title, description, publishDate) powers SEO — treat it as required.

Common Pitfalls

• Missing blank lines around lists/blocks breaks rendering on strict parsers.
• Unescaped pipes (|) inside table cells split the table — write \| instead.
• Huge images slow pages; compress to WebP/AVIF and set explicit width/height to avoid layout shift.