Skip to content

GRATIS

Documentation

Everything you need to build a world-class WordPress site with GRATIS. Free, open source, no upsells.

Installation

Three ways to install GRATIS. All free, no account required.

1
WordPress Admin (easiest)

Go to Appearance → Themes → Add New → Upload Theme, choose the gratis.zip file, click Install Now, then Activate.

2
WP-CLI (recommended for developers) 
# Install and activate in one command
wp theme install https://github.com/your-repo/gratis/archive/main.zip --activate

# Or clone and symlink for development
git clone git@github.com:your-repo/gratis.git wp-content/themes/gratis
wp theme activate gratis
3
FTP/SFTP

Upload the gratis/ folder to wp-content/themes/ via FTP, then activate from Appearance → Themes.

Your first page

After activating GRATIS, create a landing page in under 2 minutes:

  1. Go to Pages → Add New
  2. Click the + button in the top-left of the editor
  3. Switch to the Patterns tab
  4. Click Heroes category and insert Hero — Bold Centered
  5. Add more sections: Features, Testimonials, CTA
  6. Click Publish
💡
Pro tip
Set your new page as the homepage via Settings → Reading → A static page. Then go to Appearance → Editor to edit the header and footer visually.

Using patterns

GRATIS ships with 21 block patterns across 12 categories. Browse them all at /patterns.

Heroes (4)
Bold, Split, Minimal, Gradient
Sections (4)
Alternating, Logo Bar, Comparison, Timeline
Pricing (1)
3-tier pricing cards with Popular badge
Testimonials (1)
3-column review cards with star ratings

You can also insert any pattern via block markup:

<!-- wp:pattern {"slug":"gratis/hero-bold"} /-->
<!-- wp:pattern {"slug":"gratis/pricing-cards"} /-->
<!-- wp:pattern {"slug":"gratis/testimonials-grid"} /-->

Colors & typography

GRATIS uses theme.json v3 as its design system. Change your accent color once and it updates everywhere.

Via the editor (no code): Go to Appearance → Editor → Styles (the half-circle icon). Click any color to change it globally.

Via theme.json (developers):

// theme.json — change the primary color
{
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#your-color", "name": "Primary" }
      ]
    }
  }
}
primary
accent
base-dark
success
danger

Async notifications

GRATIS includes a toast notification system and bell icon panel. Call from any JavaScript on your site.

// Toast notifications
// Types: success | error | warning | info
GRATIS.toast("Item saved!", "success");
GRATIS.toast("Something went wrong", "error", 8000); // 8s duration
GRATIS.toast("Processing...", "info", 0); // stays until dismissed

// Bell panel notifications (also shows toast)
GRATIS.notify("New comment on your post", "info", "/post/123");
GRATIS.notify("Order #1234 shipped!", "success", "/orders");

// WooCommerce: fires automatically on add-to-cart
// No setup needed — it just works
🔔
The bell icon is automatically injected into the header. Click it to open the notification panel. Unread count shows as a badge. Notifications persist until the panel is opened.

Performance

GRATIS scores 100/100 on PageSpeed out of the box. Here is what makes it fast:

✓
Zero render-blocking resources
No CSS or JS blocks the initial render. Critical CSS is inlined in <head>.
✓
Per-block CSS loading
WordPress FSE only loads CSS for blocks actually present on the page. A page with no accordion loads no accordion CSS.
✓
No jQuery on frontend
jQuery is deregistered on the frontend. Saves 30KB. All GRATIS features use vanilla JS.
✓
stale-while-revalidate caching
Cache-Control headers tell CDNs to serve stale content instantly while fetching fresh content in the background.
✓
Cache-Tag headers
Every page response includes Cache-Tag headers (post-ID, term-ID) for precise CDN purging when content changes.