SREDevOps.org Ghost Theme

Ghost v6 Theme for SREDevOps.org — Multi-locale, Tailwind CSS v3, responsive, dark-mode first, with SVG icons, sidebar navigation, and tag-based language filtering.

🌐 Multi-Locale Architecture

This theme implements a template inheritance + tag-based routing strategy to serve distinct content per locale without requiring separate Ghost instances. This approach aligns with community workarounds discussed in the Ghost Forum.

Template Inheritance Pattern

┌─────────────────────────────────────┐
│ routes.yaml                          │
│ • /en/* → home-en.hbs               │
│ • /es/* → home-es.hbs               │
│ • /br/* → home-br.hbs               │
└─────────┬───────────────────────────┘
          │
          ▼
┌─────────────────────────────────────┐
│ home-*.hbs (collection template)    │
│ • Defines collection query/filter   │
│ • Renders post list via partials    │
│ • {{!< default-*.hbs}} inheritance  │
└─────────┬───────────────────────────┘
          │
          ▼
┌─────────────────────────────────────┐
│ custom-*.hbs (post/page template)   │
│ • Locale-specific post layout       │
│ • Localized metadata, TOC, comments │
│ • {{!< default-*.hbs}} inheritance  │
└─────────┬───────────────────────────┘
          │
          ▼
┌─────────────────────────────────────┐
│ default-*.hbs (layout shell)        │
│ • <html lang="*"> attribute         │
│ • Common <head>, assets, footer     │
│ • {{{body}}} injection point        │
└─────────────────────────────────────┘

💡 Key Insight: Each locale uses its own default-*.hbs layout shell to ensure proper lang attributes, meta tags, and localized UI strings. The {{{body}}} Handlebars placeholder in default-*.hbs receives the rendered output from custom-*.hbs or home-*.hbs.

Language Routing & Tag Filtering

Locale	URL Pattern	Required Tags	Exclusion Tags	Layout Shell
English (default)	`/` or `/en/{slug}/`	`en`, `hash-en`	`-es`, `-br`	`default.hbs`
Spanish	`/es/{slug}/`	`es`, `hash-es`	`-en`, `-br`	`default-es.hbs`
Portuguese (BR)	`/br/{slug}/`	`br`, `hash-br`	`-en`, `-es`	`default-br.hbs`

⚠️ Critical: The default locale (English) is configured in Ghost Admin → Settings → General → Publication language. All root-level routes (/, /page/2/, etc.) serve English content unless explicitly routed otherwise.

`routes.yaml` Core Configuration

collections:
  /es/:
    template: home-es
    permalink: /es/{slug}/
    filter: tag:es+tag:-en+tag:-br
    data: tag.es

  /en/:
    template: home-en
    permalink: /en/{slug}/
    filter: tag:en+tag:-es+tag:-br
    data: tag.en

  /br/:
    template: home-br
    permalink: /br/{slug}/
    filter: tag:br+tag:-es+tag:-en
    data: tag.br

# Fallback: English as default locale (configured in Ghost Admin)
taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

✅ Why this works: Ghost's filter syntax supports boolean logic (+ for AND, - for NOT), enabling precise content segregation per locale while maintaining a single content database. The template directive ensures each collection uses its locale-specific layout chain.

🔧 Prerequisites

Dependency	Version	Purpose
Node.js	`>=22`	Runtime for build tooling
Yarn	`>=1.22`	Package management (preferred over npm)
Ghost	`>=6.0`	Local development server
Docker (optional)	Latest	Run Ghost via official container

🐳 Ghost Local Setup: Follow the official Docker guide for a reproducible dev environment.

🚀 Installation

1. Clone & Install

# Clone the repository
git clone https://github.com/sredevopsorg/sredevopsorg-ghost-theme.git
cd sredevopsorg-ghost-theme

# Install dependencies (Yarn required)
yarn install

2. Configure Ghost

Start your local Ghost instance:

# If using Docker Compose (recommended)
docker compose up -d

# Or via Ghost-CLI
ghost start

Upload routes.yaml to Ghost Admin → Settings → Routing

Upload the theme:

Via Admin: Settings → Design → Upload theme

Or symlink for development:

ln -s /path/to/sredevopsorg-ghost-theme \
  /path/to/ghost/content/themes/sredevopsorg-ghost-theme

Critical: Set your default locale in Ghost Admin → Settings → General → Publication language (e.g., en for English). This determines which templates serve root-level routes.
Activate the theme in Ghost Admin → Design

3. Start Development Server

yarn dev

This triggers:

Tailwind CSS compilation with @tailwindcss/forms and @tailwindcss/typography
Asset bundling via Gulp
LiveReload for template/CSS changes

🔁 Hot reload is enabled for .hbs, .css, and .js files. Browser refreshes automatically on save.

✍️ Locale Content Authoring

Tagging Posts for Language Filtering

When creating content in Ghost Admin or via Markdown import:

---
title: "My Post Title"
slug: "my-post-slug"
tags:
  - en          # Primary language slug (required)
  - hash-en     # Required for filter consistency
  - Kubernetes  # Topic tags
  - SRE
---

⚠️ Critical: Omitting either en/es/br or its hash-* counterpart will cause the post to not appear in locale-specific collections due to the filter logic in routes.yaml.

Template Resolution Flow

graph LR
    A[Request: /es/my-post/] --> B[routes.yaml filter]
    B --> C{tag:es AND NOT en/br?}
    C -->|Yes| D[home-es.hbs]
    D --> E[Inherits default-es.hbs]
    E --> F[Render html lang='es']
    F --> G[Inject body from custom-es.hbs]

Creating Locale-Specific Templates

Copy the base template:

cp default.hbs default-es.hbs
cp custom.hbs custom-es.hbs
cp home.hbs home-es.hbs

Update the layout shell (default-es.hbs):

<!DOCTYPE html>
<html lang="es"> {{!-- Critical for SEO/accessibility --}}
<head>
  <meta charset="utf-8">
  <title>{{meta_title}}</title>
  {{!-- Spanish-specific OG tags --}}
  <meta property="og:locale" content="es_CL">
  {{ghost_head}}
</head>
<body class="{{body_class}}">
  {{>"components/nav-es"}} {{!-- Optional: localized nav --}}
  {{{body}}} {{!-- Injects custom-es.hbs content --}}
  {{>"components/footer"}}
</body>
</html>

Customize content templates (custom-es.hbs):
- Localize UI strings ("Autor", "Publicado", "Índice")
- Adjust date formats ({{date published_at format="DD MMM YYYY"}})
- Conditionally render locale-specific components

🏗️ Template Architecture Reference

File	Role	Inheritance	Locale Scope
`default.hbs`	Base HTML shell for English	None (root)	English (default)
`default-es.hbs`	Base HTML shell for Spanish	None (root)	Spanish
`default-br.hbs`	Base HTML shell for Portuguese	None (root)	Portuguese (BR)
`custom.hbs`	Post/page content layout	`{{!< default}}`	English
`custom-es.hbs`	Post/page content layout	`{{!< default-es}}`	Spanish
`home.hbs`	Collection/listing template	`{{!< default}}`	English
`home-es.hbs`	Collection/listing template	`{{!< default-es}}`	Spanish
`post-card-es.hbs`	Post preview partial	Standalone	Spanish

🔄 Inheritance Syntax: {{!< filename}} at the top of a template tells Ghost: "Render this file's content inside the {{{body}}} placeholder of filename".

⚙️ Theme Configuration

Customize behavior via Ghost Admin → Settings → Theme:

Option	Type	Default	Description
`background_color`	Color	`#0f172a`	Base background for dark theme
`lazy_images`	Boolean	`false`	Enable native lazy-loading on homepage
`share_buttons`	Boolean	`true`	Show social share UI on posts
`show_langs`	Boolean	`false`	Display language switcher in sidebar
`show_sso`	Boolean	`false`	Show SSO login option in sidebar

Image Size Presets

Configured in package.json → config.image_sizes:

"image_sizes": {
  "xs": { "width": 100 },
  "s":  { "width": 220 },
  "m":  { "width": 300 },
  "l":  { "width": 600 },
  "xl": { "width": 900 }
}

Use in templates: {{img_url feature_image size="l"}}

🧪 Testing & Validation

Local Testing

# Build production assets
yarn build

# Validate theme against Ghost spec
yarn test:dev    # Verbose output
yarn test:ci     # Fail on warnings (for CI)

Locale-Specific Validation

# Test Spanish routing locally
curl -I http://localhost:2368/es/ | grep "lang"
# Expected: <html lang="es">

Lighthouse Audits

The theme targets:

✅ Performance ≥ 90 (with lazy loading enabled)
✅ Accessibility ≥ 95 (proper lang attributes per locale)
✅ SEO ≥ 100 (with localized meta tags and hreflang)

Run via Chrome DevTools

🚢 Deployment

Option 1: Ghost Admin Upload

Build assets:
```
yarn build
```

Zip the theme:

zip -r sredevopsorg-ghost-theme.zip . \
  -x "*.git*" "node_modules/*" ".github/*"

Upload via Ghost Admin → Design → Upload theme

Option 2: GitHub Actions (Recommended)

This repo includes a Deploy Ghost Theme Action that:

Builds assets on push to main
Deploys via Ghost Admin API
Supports environment-specific config (staging/prod)

Configure secrets:

GHOST_ADMIN_API_URL
GHOST_ADMIN_API_KEY

🤝 Contributing

We welcome contributions aligned with our Code of Conduct.

Development Guidelines

Branching: Use feature branches (feat/locale-switcher, fix/og-tags-es)
Commits: Follow Conventional Commits
PRs: Include screenshots for UI changes; update README if behavior changes
Testing: Run yarn test:ci before submitting

Adding a New Locale (e.g., `pt` for Portugal)

Create layout shell:

cp default.hbs default-pt.hbs
# Edit: <html lang="pt">, OG locale, localized strings

Create content templates:

cp custom.hbs custom-pt.hbs
cp home.hbs home-pt.hbs
# Localize UI text, date formats, component partials

Update routes.yaml:

/pt/:
  template: home-pt
  permalink: /pt/{slug}/
  filter: tag:pt+tag:-en+tag:-es+tag:-br
  data: tag.pt

Update documentation:
- Add row to the Language Routing table
- Document any locale-specific partials (e.g., nav-pt.hbs)
Test thoroughly:
- Verify lang="pt" in rendered HTML
- Confirm tag filtering excludes other locales
- Validate SEO meta tags with og:locale="pt_PT"

📜 License

Code: MIT License — use, modify, distribute freely
Content: CC BY 4.0 (for SREDevOps.org editorial content)
Third-party assets: Respect upstream licenses (Tailwind CSS: MIT, Ghost: MIT)

🙏 Credits

Author: Nicolás Georger (@ngeorger) — SRE/DevOps practitioner, Santiago, Chile
Inspiration:
- Priority Vision's "Aspect" Theme
- @TryGhost "Source" Theme
Community: Ghost Forum contributors for multi-locale pattern validation
Tooling: Tailwind CSS, Gulp, PostCSS, GScan

🌎 LatAm Note: This theme was built with LatAm infrastructure constraints in mind — minimal external dependencies, optimized asset delivery, and community-driven localization patterns. For questions about deploying in Chile/Argentina/Brazil contexts, open an issue or reach out via SREDevOps.org.

Last updated: May 2026 | Ghost v6 compatible

Name		Name	Last commit message	Last commit date
Latest commit History 84 Commits
.github		.github
assets		assets
locales		locales
partials		partials
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
README.md		README.md
author.hbs		author.hbs
custom-es.hbs		custom-es.hbs
custom-notocbot.hbs		custom-notocbot.hbs
default-es.hbs		default-es.hbs
default.hbs		default.hbs
error-404.hbs		error-404.hbs
gulpfile.js		gulpfile.js
home-br.hbs		home-br.hbs
home-en.hbs		home-en.hbs
home-es.hbs		home-es.hbs
home.hbs		home.hbs
index.hbs		index.hbs
package.json		package.json
page-recommendations.hbs		page-recommendations.hbs
page-tags.hbs		page-tags.hbs
post.hbs		post.hbs
routes.yaml		routes.yaml
tag-es.hbs		tag-es.hbs
tag.hbs		tag.hbs
tailwind.config.js		tailwind.config.js
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

SREDevOps.org Ghost Theme

🌐 Multi-Locale Architecture

Template Inheritance Pattern

Language Routing & Tag Filtering

routes.yaml Core Configuration

📋 Table of Contents

🔧 Prerequisites

🚀 Installation

1. Clone & Install

2. Configure Ghost

3. Start Development Server

✍️ Locale Content Authoring

Tagging Posts for Language Filtering

Template Resolution Flow

Creating Locale-Specific Templates

🏗️ Template Architecture Reference

⚙️ Theme Configuration

Image Size Presets

🧪 Testing & Validation

Local Testing

Locale-Specific Validation

Lighthouse Audits

🚢 Deployment

Option 1: Ghost Admin Upload

Option 2: GitHub Actions (Recommended)

🤝 Contributing

Development Guidelines

Adding a New Locale (e.g., pt for Portugal)

📜 License

🙏 Credits

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`routes.yaml` Core Configuration

Adding a New Locale (e.g., `pt` for Portugal)

Packages