---
title: "Markdown Basics"
description: "Write documentation content using Markdown format"
---

PID^TOO|| uses Markdown for all documentation content. Markdown is a simple, readable format that converts to HTML automatically.

## What is Markdown?

Markdown is human-readable text with minimal formatting syntax:

```markdown
# This is a heading

This is regular text.

**This is bold** and _this is italic_.
```

Renders as:

- Heading 1
- Regular paragraph
- Bold and italic text

## Common Elements

### Headings

```markdown
# Heading 1 (h1)

## Heading 2 (h2)

### Heading 3 (h3)

#### Heading 4 (h4)

##### Heading 5 (h5)

###### Heading 6 (h6)
```

**Best practice:** Use one `# h1` per page (your title)

### Text Formatting

```markdown
**Bold text** or **bold**
_Italic text_ or _italic_
**_Bold and italic_**
~~Strikethrough~~
`Inline code`
```

### Lists

Unordered:

```markdown
- Item 1
- Item 2
    - Nested item
    - Another nested
- Item 3
```

Ordered:

```markdown
1. First
2. Second
3. Third
```

### Links

```markdown
[Link text](https://example.com)
[Link to page](/docs/getting-started/installation)
```

### Images

**Recommended: Use relative paths from your content collection**

```markdown
![Alt text](../assets/image-name.jpg)
![Code example](../../assets/code-example.jpg)
```

Example using an image from content/docs/assets:

![Code Example](../../assets/code-example.jpg)

**Alternative: Public folder (for shared assets)**

```markdown
![Alt text](/docs-hero.jpg)
```

**Best practices:**

- **Store images alongside content** in `content/docs/assets/` for better organization
- Always include descriptive alt text for accessibility
- Use relative paths (`../assets/`) for collection-specific images
- Use absolute paths (`/public-image.jpg`) for site-wide assets
- Optimize images before uploading (WebP recommended, or compressed JPEGs)
- Typical dimensions: 1200x630 for hero images, 800x400 for content images

**Why use content collection assets?**

- Images live with your documentation content
- Easier to manage and version control
- Better organization for multi-collection sites
- Clearer ownership and scope

### Code Blocks

Inline:

```markdown
Use `npm install` to install packages
```

Block:

````markdown
```javascript
function hello() {
    console.log("Hello world");
}
```
````

### Quotes

```markdown
> This is a blockquote
>
> It can span multiple lines
```

### Tables

```markdown
| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |
```

## Frontmatter

Every page starts with YAML frontmatter:

```yaml
---
title: "Page Title"
description: "Page description for SEO"
---
```

This comes before any content.

## Horizontal Rules

```markdown
---
or
---

or

---
```

## Next Steps

Learn advanced features:

- [Working with Images](/docs/content/markdown/working-with-images)
- [MDX Introduction](/docs/content/markdown/mdx-introduction)
- [Frontmatter Reference](/docs/content/frontmatter/overview)