# Markdown Guide

Markdown is a lightweight markup language that's easy to write and read. FolderWeb uses [Parsedown](https://parsedown.org/) to convert your Markdown files into beautiful HTML.

## Headings

Use `#` symbols for headings:

```markdown
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
```

## Emphasis

Make text **bold** or *italic*:

```markdown
*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
```

## Lists

### Unordered Lists

```markdown
- Item one
- Item two
- Item three
  - Nested item
  - Another nested item
```

### Ordered Lists

```markdown
1. First item
2. Second item
3. Third item
   1. Nested item
   2. Another nested item
```

## Links

```markdown
[Link text](https://example.com)
[Link with title](https://example.com "Title text")
```

Example: [Visit FolderWeb](#)

## Images

```markdown
![Alt text](image.jpg)
![Alt text with title](image.jpg "Image title")
```

## Code

### Inline Code

Use backticks for `inline code`:

```markdown
Use the `$variable` in your code
```

### Code Blocks

Use triple backticks for code blocks:

````markdown
```php
<?php
echo "Hello, World!";
?>
```
````

Renders as:

```php
<?php
echo "Hello, World!";
?>
```

## Blockquotes

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

Result:

> This is a blockquote.
> It can span multiple lines.

## Horizontal Rules

Create a horizontal rule with three or more hyphens, asterisks, or underscores:

```markdown
---
***
___
```

---

## Tables

```markdown
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |
```

Result:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

## Best Practices

### Use Semantic Structure

Start with `# H1` for your page title, then use `## H2`, `### H3`, etc. for sections.

### Write Readable Markdown

```markdown
# Good Example

This paragraph is easy to read with proper spacing.

## Section Heading

- List items are clear
- Each on its own line

---

# Bad Example
No spacing makes it hard to read.
##SectionWithoutSpace
-ListItemsSmashed-Together
```

### Links in FolderWeb

Internal links work best with absolute paths:

```markdown
[About page](/about/)
[Articles](/articles/)
[Specific article](/articles/2025-10-15-markdown-guide/)
```

## Advanced Features

### HTML in Markdown

You can use HTML directly in Markdown when needed:

```markdown
<div class="custom-class">
    Custom HTML content
</div>
```

### Escaping Characters

Use backslash to escape Markdown characters:

```markdown
\*This text is not italic\*
\[This is not a link\]
```

## Tips for FolderWeb

1. **Use descriptive filenames** - `article.md` is better than `content.md`
2. **Add metadata** - Use `metadata.ini` for titles, dates, and summaries
3. **Include images** - Place images in the same directory as your content
4. **Add cover images** - Use `cover.jpg` for list view thumbnails

## Further Reading

- [Markdown Guide](https://www.markdownguide.org/) - Comprehensive Markdown reference
- [Parsedown Documentation](https://parsedown.org/) - The parser FolderWeb uses
- [CommonMark Spec](https://commonmark.org/) - Markdown specification