🔨 SiteForge

Modular build system for static landing pages with automatic optimization.

WebP conversion, minification, cache busting, and complete SEO out of the box. Each page lives in its own isolated folder with HTML, SCSS, and JavaScript. Production-ready performance from day one.

---

✨ Features

• 🎨 SCSS compilation with automatic minification
• ⚡ JavaScript bundling with esbuild
• 🖼️ Image optimization - Auto-converts to WebP + optimized originals
• 🔐 Cache busting - MD5 hashes on all assets
• 🔍 SEO automation - Meta tags, Open Graph, Twitter Cards, Structured Data (JSON-LD)
• 📄 Auto-generated sitemap.xml and robots.txt
• 🔄 Live reload with BrowserSync
• 🎯 Modular structure - One folder per page

---

📋 Prerequisites

Before you begin, make sure you have installed:

• Node.js (v16 or higher)
• npm (comes with Node.js)
• A code editor (we recommend VS Code)

---

🚀 Quick Start

1. Clone the repository

git clone https://github.com/yourusername/site-forge.git
cd site-forge

2. Install dependencies

npm install

3. Configure your project

Update config.json (root folder)

Replace the example values with your own:

{
  "site": {
    "url": "https://yoursite.com", // ← Your site URL
    "name": "Your Site Name", // ← Your site name
    "defaultImage": "/assets/og-default.png"
  },
  "googleAnalytics": {
    "measurementId": "G-XXXXXXXXXX" // ← Your GA4 ID (optional)
  },
  "robots": {
    "disallow": ["/admin/"]
  },
  "favicons": {
    "enabled": true,
    "basePath": "/assets"
  },
  "seo": {
    "autoInject": true,
    "includeOpenGraph": true,
    "includeTwitterCard": true
  }
}

Update src/assets/site.webmanifest

{
  "name": "Your App Name", // ← Your app full name
  "short_name": "YourApp", // ← Your app short name
  "icons": [
    {
      "src": "/assets/web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/assets/web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "theme_color": "#ffffff", // ← Your theme color
  "background_color": "#ffffff", // ← Your background color
  "display": "standalone"
}

Find and replace https://example.com

Search for all occurrences of https://example.com in your project and replace with your actual site URL:

In VS Code:

1. Press Ctrl+Shift+H (Windows/Linux) or Cmd+Shift+H (Mac)
2. Type https://example.com in the search field
3. Type your URL (e.g., https://yoursite.com) in the replace field
4. Click "Replace All"

Files that may contain this URL:

• config.json
• src/home/meta.json
• src/404/meta.json
• Any other meta.json files you create

4. Replace brand assets

Replace the placeholder images in src/assets/ with your own:

Required files to replace:

File	Purpose	Recommended Size
favicon.ico	Browser tab icon (legacy)	32x32px or 48x48px
favicon.svg	Browser tab icon (modern)	Vector SVG
favicon-96x96.png	Browser tab icon	96x96px
apple-touch-icon.png	iOS home screen icon	180x180px
web-app-manifest-192x192.png	Web app icon (small)	192x192px
web-app-manifest-512x512.png	Web app icon (large)	512x512px
og-default.png	Social share image (default)	1200x630px
og-image.png	Social share image (home)	1200x630px
logo.png	General logo	Your preference

How to generate favicons:

You can use online tools like:

• Favicon.io - Generate from text, image, or emoji
• RealFaviconGenerator - Comprehensive favicon generator

Tips:

• Keep favicons simple and recognizable at small sizes
• Use high contrast colors
• Test how they look on both light and dark backgrounds
• For Open Graph images (og-*.png), use 1200x630px for best results on all platforms

5. Build and run

npm start

This will:

1. Clean the public/ folder
2. Build all assets (SCSS, JS, images)
3. Generate HTML with optimizations
4. Start development server with live reload
5. Open your browser at http://localhost:3000

---

📁 Project Structure

site-forge/
├── src/                      # Source files
│   ├── home/                 # Home page
│   │   ├── index.html        # HTML structure
│   │   ├── meta.json         # SEO metadata
│   │   ├── styles.scss       # Page styles
│   │   └── script.js         # Page JavaScript (optional)
│   │
│   ├── 404/                  # 404 error page
│   │   ├── index.html
│   │   ├── meta.json
│   │   └── styles.scss
│   │
│   └── assets/               # Static assets
│       ├── images/           # Images (auto-optimized)
│       ├── favicon.ico
│       ├── favicon.svg
│       └── site.webmanifest
│
├── scripts/                  # Build scripts
│   ├── build-html.js
│   ├── build-scss.js
│   ├── build-js.js
│   ├── optimize-images.js
│   ├── hash-assets.js
│   └── ...
│
├── public/                   # Generated files (gitignored)
│   ├── index.html
│   ├── 404.html
│   ├── css/
│   ├── js/
│   ├── assets/
│   ├── sitemap.xml
│   └── robots.txt
│
├── config.json               # Site configuration
├── package.json
├── .editorconfig
├── .prettierrc
└── README.md

---

📄 Creating a New Page

Each page lives in its own folder inside src/. Here's how to create one:

1. Create a new folder

mkdir src/about

2. Create the required files

src/about/index.html

<!-- Minimal structure -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <!-- Your body here -->
  </body>
</html>

src/about/meta.json (optional, but recommended)

{
  "title": "About Us - Your Site Name",
  "description": "Learn more about our company and mission.",
  "keywords": "about, company, mission",
  "author": "Your Name",
  "image": "/assets/images/about-og.jpg",
  "type": "website",
  "siteName": "Your Site Name",
  "locale": "en_US",
  "twitterCard": "summary_large_image",
  "sitemap": {
    "priority": "0.8",
    "changefreq": "monthly"
  },
  "structuredData": {
    "type": "WebPage",
    "name": "About Us",
    "description": "Learn more about our company and mission."
  }
}

src/about/styles.scss (optional)

body {
  font-family:
    system-ui,
    -apple-system,
    sans-serif;
  padding: 2rem;
  max-width: 800px;
  margin: 0 auto;
}

h1 {
  color: #333;
  margin-bottom: 1rem;
}

src/about/script.js (optional)

console.log("About page loaded!");

3. Build

npm run build

Your new page will be available at:

• Development: http://localhost:3000/about/
• Production: https://yoursite.com/about/

---

🛠️ Available Commands

Development

npm start                # Build + watch + live reload (recommended)
npm run dev              # Watch + live reload only (no initial build)

Build (Production)

npm run build            # Full production build
npm run clean            # Clean public/ folder
npm run build:scss       # Compile SCSS only
npm run build:js         # Minify JS only
npm run optimize:images  # Optimize images only
npm run hash:assets      # Add cache-busting hashes
npm run build:html       # Process HTML with injections

Code Formatting

npm run format           # Format all files (auto-fix)
npm run format:check     # Check formatting (no changes)

---

🎨 Customization

Changing Theme Colors

Update in multiple places:

1. config.json - Update theme color if needed
2. src/assets/site.webmanifest - Update theme_color and background_color
3. Your SCSS files - Update color variables

Adding Google Analytics

1. Get your GA4 Measurement ID from Google Analytics
2. Update config.json:

{
  "googleAnalytics": {
    "measurementId": "G-XXXXXXXXXX" // ← Paste your ID here
  }
}

The build script will automatically inject the tracking code.

Disabling Features

Edit config.json:

{
  "googleAnalytics": {
    "measurementId": "" // ← Leave empty to disable
  },
  "favicons": {
    "enabled": false // ← Disable favicon injection
  },
  "seo": {
    "autoInject": false, // ← Disable all SEO auto-injection
    "includeOpenGraph": false,
    "includeTwitterCard": false
  }
}

---

📸 Image Optimization

All images in src/assets/ are automatically:

1. Converted to WebP (85% quality)
2. Optimized in original format (85% quality)
3. Hashed for cache busting
4. Wrapped in <picture> tags in HTML

Supported formats

• .jpg / .jpeg
• .png
• .webp

Example

Input: src/assets/images/hero.jpg

Output:

• public/assets/images/hero.a1b2c3d4.jpg (optimized)
• public/assets/images/hero.a1b2c3d4.webp (WebP version)

In HTML:

<!-- Automatically generated -->
<picture>
  <source srcset="/assets/images/hero.a1b2c3d4.webp" type="image/webp" />
  <img src="/assets/images/hero.a1b2c3d4.jpg" alt="Hero image" />
</picture>

---

🔍 SEO Best Practices

Required files for each page

1. meta.json - Contains all SEO metadata
2. Social share image - Recommended size: 1200x630px

meta.json template

{
  "title": "Page Title - Site Name",
  "description": "A compelling description under 160 characters.",
  "keywords": "keyword1, keyword2, keyword3",
  "author": "Your Name",
  "image": "/assets/images/page-og.jpg",
  "type": "website",
  "siteName": "Your Site Name",
  "locale": "en_US",
  "twitterCard": "summary_large_image",
  "twitterCreator": "@yourusername",
  "sitemap": {
    "priority": "0.8",
    "changefreq": "weekly"
  },
  "structuredData": {
    "type": "WebPage",
    "name": "Page Title",
    "description": "Page description for search engines."
  }
}

Structured Data types

You can use any Schema.org type. Common examples:

• WebPage - Default for most pages
• Person - About/bio pages
• SoftwareApplication - Product pages
• FAQPage - FAQ sections

---

🌐 Deployment

Build for production

npm run build

This creates optimized files in public/ folder.

Deploy to popular platforms

Netlify

1. Connect your GitHub repo
2. Build command: npm run build
3. Publish directory: public

Vercel

1. Import your GitHub repo
2. Framework preset: Other
3. Build command: npm run build
4. Output directory: public

GitHub Pages

1. Build locally: npm run build
2. Copy public/ contents to your gh-pages branch
3. Or use GitHub Actions for automatic deployment

Traditional hosting (cPanel, FTP)

1. Build locally: npm run build
2. Upload contents of public/ folder to your web server
3. Point your domain to the uploaded folder

---

🔧 VS Code Setup

Recommended Extensions

The project includes .vscode/extensions.json with recommended extensions:

• Prettier - Code formatter
• EditorConfig - Maintain consistent coding styles
• ESLint - JavaScript linting
• Stylelint - CSS/SCSS linting

VS Code will prompt you to install these when you open the project.

Auto-format on save

Already configured in .vscode/settings.json! Just press Ctrl+S (or Cmd+S on Mac) and your code will auto-format.

---

🐛 Troubleshooting

Port 3000 already in use

Change the port in package.json:

"browser-sync": "browser-sync start --server public --files \"public/**/*\" --no-notify --port 3001"

Images not optimizing

Make sure Sharp is installed correctly:

npm install sharp --save-dev

If issues persist on Windows, you may need to install build tools:

npm install --global windows-build-tools

SCSS not compiling

Check that your SCSS syntax is valid. The build will show errors in the console.

Build fails

1. Delete node_modules/ and package-lock.json
2. Run npm install again
3. Try npm run build again

---

📝 Code Formatting

The project uses Prettier and EditorConfig for consistent code style.

Format all files

npm run format

Check formatting

npm run format:check

Format on save (VS Code)

Already configured! Just save your file and it will auto-format.

---

📜 License

MIT License - feel free to use this project for personal or commercial purposes.

---

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest features
• Submit pull requests

---

💬 Support

Need help? Create an issue on GitHub or reach out to the community.

---

🎯 What's Next?

• Update config.json with your information
• Update src/assets/site.webmanifest with your app name
• Replace https://example.com with your URL
• Replace all brand assets in src/assets/ (favicons, OG images, logo)
• Create your first page in src/
• Customize styles in SCSS files
• Add your content
• Build and deploy! 🚀

---

Made with ❤️ by Samuel Caetité