Quick Start Guide

Get up and running with StaticForge in minutes. Installation, project creation, and basic usage.

On This Page
⏱ 7 min read

Quick Start Guide

Ready to build something fast? You're in the right place. This guide will take you from zero to a fully functional static site in just a few minutes. We like to call it The 2-Minute Install.

What You'll Need

Just a few things before we start:

Using Lando? We've included a .lando.yml file for Lando users, but this guide focuses on the standard PHP setup. Check the project README for Lando-specific instructions.

Installation

Step 1: Get the Files

First, let's create a home for your new project and pull in StaticForge via Composer.

mkdir my-static-site
cd my-static-site
composer require eicc/staticforge

Step 2: Initialize Your Project

Now, let's set the stage. Run the initialization command to set up your directory structure, configuration, and templates:

php vendor/bin/staticforge.php site:init

You will see output similar to this:

StaticForge Initialization
==========================

[OK] Created directory: content
[OK] Created directory: templates
[OK] Created directory: public
[OK] Created configuration: .env
[OK] Created configuration: siteconfig.yaml
[OK] Installed default template: staticforce
[OK] Created sample content: content/index.md

Success! Your project is ready.

This command does the heavy lifting for you:

Step 3: Configure Your Site (Optional)

Authentication secrets and environment-specific settings (like URLs) live in your .env file, but your site identity lives in siteconfig.yaml.

1. Environment Settings (.env): Use this for things that change between environments (Dev vs Production).

SITE_BASE_URL="http://localhost:8000"
TEMPLATE="staticforce"

2. Site Identity (siteconfig.yaml): Use this for public information about your site. Open siteconfig.yaml and edit:

site:
  name: "My Static Site"
  tagline: "Built with ❤️ and PHP"
  description: "A super fast site built with StaticForge"

Step 4: Generate Your Site

This is the moment of truth. Build your static site using the render command:

php vendor/bin/staticforge.php site:render

You'll see output confirming the generation:

Building Site...
================

[+] Discovered 5 files
[+] Processing content/index.md... OK
[+] Processing content/about.md... OK
[+] Generating Sitemap... OK
[+] Generating RSS Feed... OK

[OK] Site generation complete! (0.42s)

Your site is now ready in the public/ directory!

Step 5: See It Live

Let's take a look at what you built. Start the built-in development server:

php vendor/bin/staticforge.php site:devserver

Open your browser to http://localhost:8000 to see your new site!

Creating Your First Page

StaticForge includes a starter homepage (content/index.md), but let's make your mark by creating a new page.

Step 1: Create a Content File

You can create content files manually, or use the handy CLI command. Let's use the CLI:

php vendor/bin/staticforge.php make:content "Hello World"

This creates a new file at content/hello-world.md. Open it in your editor, and you'll see it's ready for you:

---
title: "Hello World"
date: "2026-02-12"
---

# Hello World

Write your content here...

Understanding the Structure:

Feel free to edit the content to say whatever you like!

Step 2: Regenerate Your Site

Now tell StaticForge to regenerate your site with the new page:

php vendor/bin/staticforge.php site:render

You'll see:

✓ Site generation complete!
  Generated 2 pages

StaticForge just:

  1. Read your content files
  2. Converted the Markdown to HTML
  3. Applied your chosen template
  4. Saved them in the public/ directory

Step 3: View Your Page

If you started the local server in Step 5:

  1. Open your browser
  2. Go to http://localhost:8000/hello-world.html
  3. See your beautiful new page! 🎉

Not using the local server? Just open public/hello-world.html directly in your browser.

Step 4: Go Live

Built something you're proud of? It's time to share it.

StaticForge includes a smart deployment tool (site:upload) that handles everything for you. It optimizes your build for production and syncs only the changes to your server.

👉 See the Deployment Guide to configure your server and launch your site.

Try Different Content Formats

StaticForge supports both Markdown and HTML. Let's try an HTML page for when you need more control.

Create content/about.html:

<!--
---
title: "About Me"
description: "Learn more about me"
---
-->

<h1>About Me</h1>

<p>I'm building a static site with StaticForge!</p>

<h2>Why StaticForge?</h2>
<ul>
  <li>It's fast</li>
  <li>It's simple</li>
  <li>It's built with PHP</li>
</ul>

Notice the difference:

Generate your site again:

php vendor/bin/staticforge.php site:render

Now visit http://localhost:8000/about.html to see it!

Adding Images and Assets

You can add images, custom CSS, or JavaScript to your site by placing them in the content/assets directory.

  1. Create the directory structure:

    mkdir -p content/assets/images

  2. Add an image (e.g., my-photo.jpg) to content/assets/images/.

  3. Reference it in your content:

    ![My Photo](/assets/images/sf_quickstart_hero.jpg)

StaticForge will automatically copy everything from content/assets to public/assets when you build your site.

Adding Pages to Your Menu

Want your pages to show up in the navigation menu? Add a menu value to the frontmatter:

---
title: "Blog"
menu: 1.1
---

# My Blog

Check out my latest posts!

How menu positioning works:

Want a page in multiple menus? Just list them with commas:

---
title: "Contact"
menu: 1.5, 2.3
---

This puts your Contact page in the main menu AND the footer menu!

Regenerate your site to see the menu update!

Organizing with Categories

Keep related content together using categories:

---
title: "My First Blog Post"
category: "blog"
---

# My First Blog Post

This is a blog post about StaticForge!

StaticForge automatically:

What's Next?

Congratulations! 🎉 You've created your first static site with StaticForge!

Want a Different Look?

The default template gets you started, but you can easily switch things up. You can install new templates via Composer:

composer require vendor/template-name

StaticForge copies the template to your templates/ directory. Activate it by setting TEMPLATE="template-name" in your .env file.

Quick Tips

Regenerate after every change: StaticForge doesn't watch for changes. Run php vendor/bin/staticforge.php site:render after editing content or templates.

Try different templates: Change TEMPLATE in .env to try out different templates - staticforce (default) or sample.

Keep frontmatter simple: Only add metadata you actually need. At minimum, just set a title.

Use Markdown for content: Markdown is easier to write and read than HTML. Save HTML for special layouts.

Need Help?

Happy site building! 🚀