folderweb/docs/02-tutorial/01-adding-content.md

# Adding Content

FolderWeb turns your folder structure into a website. Every file becomes a page, every folder becomes a URL path.

## The Basic Idea

```
content/
├── about.md          → yoursite.com/about/
├── blog/
│   └── index.md      → yoursite.com/blog/
└── contact.html      → yoursite.com/contact/
```

No configuration required.

## Content Formats

FolderWeb supports three content formats. You can use them individually or mix them within a single page.

### Markdown (`.md`)

```markdown
# My Page Title

This is a paragraph with **bold** and *italic* text.

- Lists work
- And so do [links](https://example.com)
```

Converted to HTML using [Parsedown](https://parsedown.org/) with caching.

### HTML (`.html`)

```html
<h1>My Page</h1>
<p>Plain HTML, rendered as-is.</p>
<div class="custom-widget">
  Full control over markup.
</div>
```

### PHP (`.php`)

```php
<?php
$currentYear = date('Y');
echo "<p>Copyright {$currentYear}</p>";
?>
```

PHP files are executed server-side. Be careful with user input and security.

## Folder Structure as URL Structure

Your folder hierarchy determines your URLs:

```
content/
├── index.md                    → /
├── about.md                    → /about/
├── blog/
│   ├── index.md                → /blog/
│   ├── 2024-12-15-first-post/
│   │   └── index.md            → /blog/first-post/
│   └── 2024-12-20-second-post/
│       └── index.md            → /blog/second-post/
└── projects/
    ├── index.md                → /projects/
    └── my-project/
        └── index.md            → /projects/my-project/
```

- Folder names become URL slugs
- Date prefixes (`YYYY-MM-DD-`) are stripped from URLs but preserved for sorting
- Trailing slashes are enforced (`/about` redirects to `/about/`)

## Multiple Files in One Page

Multiple content files in one directory render as a single page, combined in filename order.

**Prefix filenames with numbers to control the order:**

```
content/portfolio/
├── 10-hero.php       # Renders first  — dynamic PHP banner
├── 20-intro.md       # Renders second — Markdown prose
├── 30-gallery.html   # Renders third  — HTML layout
└── 40-contact.md     # Renders last   — Markdown form
```

All four files render as one page at `/portfolio/`. You can mix `.md`, `.html`, and `.php` freely — use whichever format fits each section best.

**Why number prefixes?** Files are sorted using natural sort, so `10-` comes before `20-` comes before `30-`. Using increments of 10 leaves room to insert new sections later without renaming existing files. Files without a number prefix sort after numbered files.

## Dates in Folder Names

FolderWeb extracts dates from folder names automatically:

```
content/blog/
├── 2024-12-15-my-first-post/    # Date: December 15, 2024
├── 2024-12-20-another-post/     # Date: December 20, 2024
└── 2025-01-01-new-year-post/    # Date: January 1, 2025
```

The `YYYY-MM-DD-` prefix is stripped from the URL:

- Folder: `2024-12-15-my-first-post`
- URL: `/blog/my-first-post/`

Dates are formatted based on your configured language.

## Assets

Drop images and other files directly in your content folders:

```
content/blog/my-post/
├── index.md
├── cover.jpg          # Cover image (automatic)
├── diagram.png        # Referenced in content
└── styles.css         # Page-specific styles
```

Reference in Markdown:

```markdown
![Alt text](diagram.png)
```

**Cover images:** Name your image `cover.jpg`, `cover.png`, or `cover.webp`. FolderWeb uses it automatically in list views and social media meta tags.

## Metadata

Add a `metadata.ini` file to configure a page:

```
content/blog/my-post/
├── index.md
└── metadata.ini
```

Basic metadata:

```ini
title = "My Awesome Post"
summary = "A short description for list views"
date = "2024-12-15"
```

More options:

```ini
title = "My Post"
summary = "Short description"
date = "2024-12-15"
search_description = "SEO description for search engines"
menu = 1                # Show in navigation menu
menu_order = 10         # Menu position (lower = first)

[settings]
show_date = true        # Display date on page
hide_list = false       # Force page view even with subdirectories
```

See the [Metadata Reference](../03-reference/02-metadata.md) for all options.

## List Views vs. Page Views

FolderWeb automatically decides whether to show a **list** or a **page**:

**List view** — directory has subdirectories:
```
content/blog/
├── index.md                    # Intro content (shown above list)
├── metadata.ini
├── 2024-12-15-first-post/
└── 2024-12-20-second-post/
```
Result: `/blog/` shows a list of posts.

**Page view** — directory has only files:
```
content/about/
└── index.md
```
Result: `/about/` shows the page content.

Set `hide_list = true` in `metadata.ini` to force page view even when subdirectories exist.

## Custom URL Slugs

Override the folder name as URL with metadata:

```ini
slug = "short-title"
```

Folder `2024-12-15-very-long-title/` becomes `/blog/short-title/` instead of `/blog/very-long-title/`.

## Navigation Menu

Add pages to the navigation menu:

```ini
title = "About Us"
menu = 1              # Show in menu
menu_order = 20       # Position (lower = first)
```

Items are sorted by `menu_order`, then alphabetically by title.

## Examples

### Blog Post

```
content/blog/2024-12-15-my-first-post/
├── index.md
├── cover.jpg
└── metadata.ini
```

**index.md:**
```markdown
# My First Post

Blog post content goes here.

![Photo](cover.jpg)
```

**metadata.ini:**
```ini
title = "My First Post"
summary = "An introduction to my blog"
```

### Multi-Format Page

```
content/services/
├── 10-hero.php
├── 20-intro.md
├── 30-pricing.html
└── metadata.ini
```

All content files render together as one page at `/services/`, in number-prefix order.

## Next Steps

- [Styling](02-styling.md) — Customize colors, fonts, and layout
- [Templates](03-templates.md) — Control how content is presented
- [Internationalization](../03-reference/04-internationalization.md) — Multi-language support