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

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:

cp -r app/default custom

Windows (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

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 installed, there's a ready-made setup:

cd devel
podman-compose up

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

Using PHP's Built-in Server:

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:

# 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:

# 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:

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

Nginx Configuration

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.