folderweb/docs/tutorial/00-getting-started.md

# Getting Started

Welcome to FolderWeb! This tutorial will guide you through creating your first website from scratch in just a few minutes.

## What You'll Build

By the end of this tutorial, you'll have a simple website with:
- A home page
- An about page
- A blog with multiple posts
- Custom styling

## Prerequisites

- PHP 8.4 or higher
- A web server (Apache, Nginx, or PHP's built-in server)
- Basic understanding of file systems

## Step 1: Set Up Your Project

First, create your project directory:

```bash
mkdir my-website
cd my-website
```

Copy the FolderWeb framework files into your project:

```bash
# Copy app/ directory with all framework files
cp -r /path/to/folderweb/app ./app

# Create your content directory
mkdir content
```

## Step 2: Create Your First Page

Create a simple home page by adding a Markdown file to your content directory:

```bash
echo "# Welcome to My Website" > content/index.md
echo "" >> content/index.md
echo "This is my first page built with FolderWeb." >> content/index.md
```

## Step 3: Start the Server

Use PHP's built-in server to view your site:

```bash
php -S localhost:8000 -t . app/router.php
```

Open your browser and navigate to `http://localhost:8000`. You should see your home page!

## Step 4: Add Another Page

Create an "about" page. FolderWeb uses folder-based routing, so the folder name becomes the URL:

```bash
mkdir content/about
echo "# About Me" > content/about/index.md
echo "" >> content/about/index.md
echo "I'm learning FolderWeb, a minimalist PHP framework." >> content/about/index.md
```

Visit `http://localhost:8000/about/` to see your new page.

## Step 5: Create a Blog

Now let's create a blog with multiple posts. When a folder contains subdirectories, FolderWeb automatically creates a list view:

```bash
# Create blog directory
mkdir -p content/blog

# Create first post
mkdir content/blog/2025-11-01-my-first-post
echo "# My First Post" > content/blog/2025-11-01-my-first-post/index.md
echo "" >> content/blog/2025-11-01-my-first-post/index.md
echo "This is my first blog post!" >> content/blog/2025-11-01-my-first-post/index.md

# Create second post
mkdir content/blog/2025-11-02-second-post
echo "# Second Post" > content/blog/2025-11-02-second-post/index.md
echo "" >> content/blog/2025-11-02-second-post/index.md
echo "Already on my second post!" >> content/blog/2025-11-02-second-post/index.md
```

Visit `http://localhost:8000/blog/` to see your blog listing. Notice how FolderWeb automatically:
- Extracted dates from the folder names (2025-11-01, 2025-11-02)
- Created clickable links to each post
- Formatted the dates in Norwegian style

## Step 6: Add Metadata

Let's enhance your blog posts with metadata. Create a `metadata.ini` file in one of your posts:

```bash
cat > content/blog/2025-11-01-my-first-post/metadata.ini << 'EOF'
title = "My Amazing First Post"
date = "2025-11-01"
summary = "A brief introduction to my blogging journey with FolderWeb."
EOF
```

Refresh `http://localhost:8000/blog/` and you'll see the summary appears in the listing.

## Step 7: Add a Cover Image

Make your blog more visual by adding a cover image:

```bash
# Copy or download an image as cover.jpg in your post folder
# For this example, we'll just note where it should go:
# content/blog/2025-11-01-my-first-post/cover.jpg
```

If you add a `cover.jpg`, `cover.png`, or `cover.webp` file to a post folder, it will automatically appear in the blog listing.

## Step 8: Customize Your Blog Layout

Change how your blog is displayed by setting a different template. Create metadata for the blog directory:

```bash
cat > content/blog/metadata.ini << 'EOF'
title = "My Blog"
page_template = "list-grid"
EOF
```

Refresh `http://localhost:8000/blog/` to see a grid layout instead of a simple list.

Available list templates:
- `list` (default) - Simple list
- `list-grid` - Grid with cover images
- `list-card-grid` - Card-style grid
- `list-faq` - Expandable Q&A format

## Step 9: Add Custom Styles

Create a custom stylesheet to override the default styles:

```bash
mkdir -p custom/styles
cat > custom/styles/base.css << 'EOF'
:root {
    --color-primary: oklch(0.55 0.20 30);  /* Orange instead of blue */
    --font-heading: "Arial", sans-serif;    /* Sans-serif headings */
}
EOF
```

Refresh your browser to see your custom colors.

## Step 10: Multi-File Pages

FolderWeb can combine multiple files into a single page. This is useful for long documentation:

```bash
# Create a documentation page with multiple sections
mkdir content/docs
echo "# Introduction" > content/docs/00-intro.md
echo "Welcome to the docs!" >> content/docs/00-intro.md

echo "# Installation" > content/docs/01-install.md
echo "How to install the software." >> content/docs/01-install.md

echo "# Configuration" > content/docs/02-config.md
echo "How to configure it." >> content/docs/02-config.md
```

Visit `http://localhost:8000/docs/` and all three files render as one continuous page.

## What You've Learned

Congratulations! You now know how to:

- ✓ Create pages using Markdown files
- ✓ Use folder-based routing
- ✓ Create blog listings with automatic date extraction
- ✓ Add metadata to customize content
- ✓ Use cover images
- ✓ Switch between different list templates
- ✓ Apply custom styling
- ✓ Create multi-file pages

## Next Steps

- Explore the [How-To Guides](../how-to/) for specific tasks
- Read the [Reference Documentation](../reference/) for complete feature details
- Understand the [Philosophy](../explanation/philosophy.md) behind FolderWeb
- Learn about [multi-language support](../how-to/multi-language.md)
- Discover [template customization](../how-to/custom-templates.md)