ruben/folderweb
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
folderweb/docs/tutorial/00-getting-started.md
Ruben ad516600bb Add docs
2025-11-02 13:46:47 +01:00

5.6 KiB
Raw Blame History

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:

mkdir my-website
cd my-website

Copy the FolderWeb framework files into your project:

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

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:

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:

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:

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

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:

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

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:

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:

# 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