Lesson 01 of 10

Getting Started

Install OrbLayout, create your first project, and understand how the build pipeline works. By the end of this lesson, you'll have a working static site.

In This Lesson

  1. What is OrbLayout?
  2. Installation
  3. Scaffolding a Project
  4. Project Structure
  5. Your First Build
  6. Dev Server & Live Reload
  7. How It Works
  8. Checkpoint

What is OrbLayout?

OrbLayout is a static site builder that lets you write HTML with superpowers. Think of it as a middle ground between hand-coding HTML and using a full JavaScript framework like React or Next.js.

With OrbLayout you get:

  • Layouts — Define the page shell (HTML boilerplate) once, reuse everywhere
  • Components — Build reusable UI blocks like cards, headers, footers
  • Props — Pass data to components just like React props
  • Loops & Conditionals — Dynamically render lists and toggle content
  • Filters — Transform data inline (uppercase, slugify, truncate, etc.)
  • Zero runtime — Output is pure HTML. No JavaScript shipped to the browser
💡

Why OrbLayout? If you need a website that's fast, SEO-friendly, and simple — but you're tired of copy-pasting the same header/footer into 50 HTML files — OrbLayout is for you.

Installation

OrbLayout runs on Node.js 16+. Make sure you have Node installed first.

Option A: npm (recommended)

Terminal bash 
# Install as a project dependency
npm install orblayout

# Or install globally
npm install -g orblayout

Option B: Clone from GitHub

Terminal bash 
git clone https://github.com/rukkit-official/orblayout.git
cd orblayout
npm install

Verify installation

Terminal bash 
npx orb version
# → OrbLayout v1.2.0
📝

If installed globally, you can use orb directly instead of npx orb.

Scaffolding a Project

The fastest way to start is with orb init. This creates the entire project structure for you.

Terminal bash 
mkdir my-website
cd my-website
npx orb init

This generates:

Output text 
✓ Created orb.config.json
✓ Created pages/index.orb
✓ Created layouts/main.layout
✓ Created components/header.orb
✓ Created components/footer.orb

  Project ready! Run 'orb dev' to start.

Project Structure

Every OrbLayout project follows this folder structure:

File Tree structure 
my-website/
│
├── 📄 orb.config.json     ← Project configuration
│
├── 📂 pages/               ← Your pages (.orb files)
│   ├── index.orb           ← → dist/index.html
│   ├── about.orb           ← → dist/about.html
│   └── blog/
│       └── post.orb        ← → dist/blog/post.html
│
├── 📂 components/           ← Reusable components
│   ├── header.orb
│   ├── footer.orb
│   └── card.orb
│
├── 📂 layouts/              ← Page layout templates
│   └── main.layout
│
├── 📂 assets/               ← Static files (images, CSS)
│   ├── style.css
│   └── logo.png
│
└── 📂 dist/                 ← Build output (auto-generated)
    ├── index.html
    └── about.html
Folder File Type Purpose
pages/ .orb Each file becomes an HTML page in dist/
components/ .orb Reusable UI blocks referenced by pages/layouts
layouts/ .layout Page skeletons (HTML boilerplate)
assets/ any Static files copied as-is to dist/assets/
dist/ .html Final output — pure HTML, ready to deploy

Your First Build

Let's build the site and see the output.

Terminal bash 
npx orb build
Output text 
  ╔═══════════════════════════════════════╗
  ║     ◉  O r b L a y o u t  v1.2.0    ║
  ║     Static Site Builder               ║
  ╚═══════════════════════════════════════╝
  
  Building pages...

  ✓ index.orb → index.html
  ✓ about.orb → about.html

  Done! 2 page(s) compiled in 25ms
  Output: dist/

Open dist/index.html in your browser — that's your compiled page!

Build with minification

For production, add --minify to compress the HTML output:

Terminal bash 
npx orb build --minify

Dev Server & Live Reload

During development, use the dev server for instant feedback:

Terminal bash 
npx orb dev
Output text 
  ◉ OrbLayout Dev Server
  
  Local: http://localhost:3000
  
  Watching for changes...
  [SSE] Live reload enabled

The dev server:

  • Watches all .orb and .layout files for changes
  • Rebuilds automatically when you save
  • Reloads your browser via SSE (Server-Sent Events) — no browser extension needed
  • Serves clean URLs (/about instead of /about.html)

Custom port

Terminal bash 
npx orb dev --port 8080
⚡

Hot tip: Keep orb dev running in one terminal tab while you edit files. Your browser will auto-refresh every time you save!

How It Works

OrbLayout's build pipeline is simple:

Pipeline flow 
   .orb page file
        │
        ▼
   ┌──────────┐
   │  Parser   │ ← Extracts layout, components, data, loops, etc.
   └────┬─────┘
        ▼
   ┌──────────┐
   │ Compiler  │ ← Resolves everything into pure HTML
   └────┬─────┘
        ▼
   ┌──────────┐
   │ Builder   │ ← Writes .html files to dist/
   └──────────┘
        │
        ▼
   Pure .html file

The key insight: everything happens at build time. Your visitors receive plain HTML files. No JavaScript framework loads, no API calls fire, no client-side rendering happens. It's just HTML.

✅ Lesson 1 Checkpoint

Before moving on, make sure you can:

  1. Install OrbLayout via npm install orblayout
  2. Scaffold a project with npx orb init
  3. Build the site with npx orb build
  4. Start the dev server with npx orb dev
  5. Open dist/index.html in a browser and see your page
← Back Course Home