folderweb/docs/01-getting-started/index.md

# Getting Started with FolderWeb

Welcome to FolderWeb—a delightfully minimal PHP framework that turns your folder structure into a website. No build steps, no package managers, no JavaScript frameworks. Just files and folders doing what they do best.

## What You Need

- **PHP 8.4+** — Modern PHP with all the good stuff
- **A web server** — Apache, Nginx, or just PHP's built-in server for local development
- **A text editor** — Whatever makes you happy

That's it. No npm, no webpack, no node_modules folder the size of the observable universe.

## Quick Start (5 Minutes)

### 1. Get the Code

```bash
git clone https://github.com/yourusername/folderweb.git
cd folderweb
```

### 2. Set Up Your Custom Directory

FolderWeb separates framework code (`app/`) from your customizations (`custom/`). Copy the defaults to get started:

**Unix/Linux/macOS:**
```bash
cp -r app/default custom
```

**Windows (PowerShell):**
```powershell
Copy-Item -Recurse app\default custom
```

**Or just:** Copy the `app/default` folder and rename it to `custom` using your file manager.

### 3. Create Your Content Directory

```bash
mkdir content
```

This is where your actual website content lives—separate from the framework.

### 4. Fire It Up Locally

**Using Podman (Recommended):**

If you have [Podman](https://podman.io/) installed, there's a ready-made setup:

```bash
cd devel
podman-compose up
```

Visit `http://localhost:8080` and you're live.

**Using PHP's Built-in Server:**

```bash
php -S localhost:8080 -t .
```

Simple, but you'll need to configure routing manually for production.

### 5. Make Your First Page

Create a file at `content/hello.md`:

```markdown
# Hello, World!

This is my first page. Look ma, no build step!
```

Visit `http://localhost:8080/hello/` and there it is.

**Pro tip:** Notice the trailing slash? FolderWeb enforces them. Folders are folders, after all.

## What Just Happened?

FolderWeb looked at your request (`/hello/`), found `content/hello.md`, processed the Markdown into HTML, wrapped it in a template, and served it. All in milliseconds.

The magic is simple:
- **Folders = URLs:** Your directory structure is your site structure
- **Files = Content:** Drop a `.md`, `.html`, or `.php` file and it renders
- **Templates = Presentation:** HTML wrappers that make everything pretty
- **Metadata = Configuration:** Optional `.ini` files for titles, dates, and settings

## Next Steps

Now that you're up and running, you can:

1. **[Add more content](#)** — Learn about Markdown files, metadata, and organizing pages
2. **[Customize the design](#)** — Edit templates and CSS to make it yours
3. **[Deploy to production](#)** — Get your site online with a web host

Or just keep making pages. It's your website—do what makes you happy.

---

## Deploying to Production

When you're ready to go live, you'll need a web host with PHP support. Look for:

- **PHP 8.4+** (or at least 8.0, but why settle?)
- **Apache or Nginx** with mod_rewrite or equivalent
- **SSH access** (optional, but makes life easier)

Most shared hosting providers offer this. Avoid anything that says "managed WordPress only"—you're too cool for that.

### Deployment with Symlinks (Recommended)

Keep the framework separate from the web root for easy upgrades:

```bash
# Your server structure:
/home/yourusername/
├── folderweb/           # Git repo (not public)
│   ├── app/
│   └── custom/
├── content/             # Your content (not public)
└── public_html/         # Web root (public)
    ├── app -> ../folderweb/app/         # Symlink
    ├── custom -> ../folderweb/custom/   # Symlink
    └── content -> ../content/           # Symlink
```

**Why?** When you update FolderWeb, just `git pull` and you're done. No copying files, no risk of overwriting customizations.

### Apache Configuration

If your host lets you use `.htaccess`, FolderWeb will handle routing automatically. Otherwise, add this to your Apache config:

```apache
<Directory /path/to/public_html>
    RewriteEngine On
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)$ /app/router.php [L,QSA]
</Directory>
```

### Nginx Configuration

```nginx
location / {
    try_files $uri $uri/ /app/router.php?$query_string;
}
```

That's it. Upload your files, point your domain, and you're live.

---

## What's Next?

Ready to dive deeper? Head to the [Tutorial](#) to learn how to:
- Organize content with folders and metadata
- Customize templates and styles
- Add multilingual support
- Create list views and navigation menus

Or jump straight to the [Reference](#) if you're the "read the manual" type.