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.

# 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 to convert Markdown to HTML, with caching for performance.

HTML (.html)

When you need more control or already have 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
$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 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 (strnatcmp), 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 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:

![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:

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

More options:

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:

slug = "custom-url-path"

Example:

content/blog/2024-12-15-very-long-title-that-i-regret/
└── metadata.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:

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:

# My First Post

This is my blog post content.

![Photo](cover.jpg)

metadata.ini:

title = "My First Post"
summary = "An introduction to my blog"

Multi-Section 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.

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.