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

# Adding Content

FolderWeb turns your folder structure into a website. That's not marketing speak—it's literally how it works. Let's explore what that means in practice.

## The Basic Idea

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

Every file becomes a page. Every folder becomes a URL path. No configuration required.

## File Types

FolderWeb recognizes three content types:

### Markdown (`.md`)

The bread and butter of content creation. Write in Markdown, get HTML.

```markdown
# My Page Title

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

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

## Subheading

More content here.
```

FolderWeb uses [Parsedown](https://parsedown.org/) to convert Markdown to HTML, with caching for performance.

### HTML (`.html`)

When you need more control or already have HTML:

```html
<h1>My Page</h1>
<p>This is plain HTML.</p>
<div class="custom-widget">
  Whatever you want.
</div>
```

### PHP (`.php`)

For dynamic content:

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

<h2>Latest Posts</h2>
<?php
$posts = ['Post 1', 'Post 2', 'Post 3'];
foreach ($posts as $post) {
    echo "<li>{$post}</li>";
}
?>
```

**Important:** PHP files are executed, so 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/
```

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

## Multiple Files in One Page

You can combine multiple content files in a single directory. They render in **alphabetical order**:

```
content/portfolio/
├── 00-hero.php       # Renders first
├── 01-intro.md       # Renders second
├── 02-gallery.html   # Renders third
└── 03-contact.md     # Renders last
```

All four files render as one page at `/portfolio/`.

**Use case:** Build pages from modular components—header, content, footer, etc.

## Dates in Folder Names

FolderWeb automatically extracts dates from folder names:

```
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 date format is `YYYY-MM-DD-` and it's **stripped from the URL**:

- Folder: `2024-12-15-my-first-post`
- URL: `/blog/my-first-post/`
- Date: Extracted and available in templates

Dates are automatically formatted based on your language (e.g., "15. desember 2024" in Norwegian).

## Adding Assets (Images, Files)

Drop assets 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 cover image `cover.jpg`, `cover.png`, or `cover.webp`. FolderWeb automatically uses it in list views and social media meta tags.

## Metadata Files

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

```
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-friendly 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       # Don't show list view even if subdirectories exist
```

See the [Metadata Reference](#) for all available 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
├── metadata.ini                # List configuration
├── 2024-12-15-first-post/
└── 2024-12-20-second-post/
```

Result: `/blog/` shows a list of posts with the intro content at the top.

**Page view** (directory has only files):
```
content/about/
└── index.md
```

Result: `/about/` shows just the page content.

**Override:** Use `hide_list = true` in `metadata.ini` to force page view even with subdirectories.

## Custom URL Slugs

Don't like your folder name as the URL? Override it with metadata:

```ini
slug = "custom-url-path"
```

**Example:**

```
content/blog/2024-12-15-very-long-title-that-i-regret/
└── metadata.ini
```

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

URL becomes `/blog/short-title/` instead of `/blog/very-long-title-that-i-regret/`.

## Navigation Menus

Add pages to the navigation menu with metadata:

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

Menu items are sorted by `menu_order`, then alphabetically by title.

## Practical Examples

### Simple Blog Post

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

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

This is my blog post content.

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

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

### Multi-Section Page

```
content/services/
├── 00-hero.php
├── 01-intro.md
├── 02-pricing.html
└── metadata.ini
```

All files render together as one page at `/services/`.

### Documentation Site

```
content/docs/
├── index.md
├── getting-started/
│   └── index.md
├── tutorial/
│   ├── index.md
│   ├── basics.md
│   └── advanced.md
└── reference/
    └── index.md
```

Creates a hierarchical documentation structure with automatic list views.

## What's Next?

Now that you know how to add content, learn how to:
- **[Customize styling](#)** — Make it look like your own
- **[Create templates](#)** — Control how content is presented
- **[Add multilingual support](#)** — Reach a global audience

Or jump to the [Reference](#) for detailed documentation on metadata, templates, and configuration.