Skip to content

README.md

Latest commit

 

History

History
161 lines (112 loc) · 6.8 KB

README.md

File metadata and controls

161 lines (112 loc) · 6.8 KB
Raw

Ghost Theme Starter Kit

Ghost CMS Vite Tailwind CSS

A minimal Ghost CMS theme starter that combines Ghost templates with modern tools (Vite + Tailwind CSS 4) to help you build and deploy themes quickly. Clone it, customize it, and use it for personal, client, or commercial projects.

Features

  • Vite & HMR: Hot Module Replacement for Handlebars (.hbs), CSS/Tailwind, and JavaScript assets
  • Tailwind CSS 4: Next-gen utility-first styling with @tailwindcss/typography and CSS variable design tokens
  • Code Syntax Highlighting: Automatic code block highlighting via highlight.js with a built-in copy button (highlightjs-copy)
  • Ready-to-ship Structure: Complete layout templates, responsive header/footer, pagination, and Lucide icons
  • Automatic Image Optimization: Integrated Sharp image optimization pipeline via vite-plugin-image-optimizer
  • One-command Packaging: Production build exports an optimized ZIP file ready for Ghost upload

Prerequisites

  • Node.js 22+ and pnpm installed globally
  • A local or remote Ghost instance (v6+) to test the theme

Quick Start

  1. Clone the repository:

    git clone https://github.com/frontendweb3/ghost-theme-starter-kit.git
cd ghost-theme-starter

  2. Install dependencies:

    pnpm install

  3. Develop with Hot Module Replacement (HMR):

    pnpm dev

    This starts the Vite dev server on http://localhost:5173. Open your local Ghost site at http://localhost:2368 to see live updates.

  4. Production build:

    pnpm build

    This compiles assets into assets/dist/ and generates the theme .zip file for deployment.

How Hot Module Replacement (HMR) Works with Ghost CMS

Ghost CMS runs on http://localhost:2368 and Vite dev server runs on http://localhost:5173.

  • Client Injection: assets/js/hmr.js automatically detects localhost / 127.0.0.1 and injects Vite's client script (@vite/client) and assets/js/main.js.
  • Template Reloads (.hbs): When you edit any .hbs Handlebars template, the custom ghostHmrPlugin in vite.config.ts invalidates Vite's module graph (allowing Tailwind CSS v4 to scan for new classes) and sends a full-reload signal to refresh the page in your browser.
  • Instant CSS & JS Updates (.css / .js): Styling changes (Tailwind classes) and JS changes update instantly in the browser via Vite's native HMR without refreshing the page.

Code Syntax Highlighting (Highlight.js)

Code syntax highlighting is pre-configured for code blocks inside posts and pages.

  • Implementation: Located in assets/js/highlight.js and loaded dynamically via assets/js/post.js on post/page templates ({{#is "post, page"}}).

  • Features:

    • Theme: GitHub Dark (highlight.js/styles/github-dark.css)
    • Copy Button: Uses highlightjs-copy to display a one-click copy button on hover for <pre><code> blocks.

  • Supported Languages: bash, css, javascript, typescript, json, xml/html.

  • Adding Languages: Import and register new languages in assets/js/highlight.js:

    import python from 'highlight.js/lib/languages/python';
hljs.registerLanguage('python', python);

Using with Ghost

  • Copy the built theme output into your Ghost installation's content/themes/<your-theme>/ directory (or symlink it during development).
  • Restart Ghost so it picks up the new theme, then activate it in the Ghost admin UI.
  • Adjust the config values in package.json (for example, posts_per_page and card_assets) to match your design needs.

Project Structure

  • Templates: author.hbs, default.hbs, index.hbs, post.hbs, page.hbs, tag.hbs, error-404.hbs
  • Partials: partials/ (header, footer, navigation, pagination, cards)
  • Components: partials/components (button and icon). These are reusable UI partials built with Lucide icons.
  • Assets: assets/ (CSS, JS, images) compiled by Vite into assets/dist/
  • Build config: vite.config.ts

Styling

  • Tailwind CSS 4 is included via @tailwindcss/vite and @tailwindcss/typography.
  • Add utility classes in assets/css/styles.css and extend via Tailwind config or CSS variables.

Lucide Icon Guide

This starter uses lucide with a reusable Handlebars partial.

  1. Add the icon import in assets/js/icons.js.

    import { createIcons, Sun, Moon, Search, UserRound, SendHorizontal, Heart } from 'lucide';

  2. Register it in the icons object inside createIcons.

    createIcons({
  icons: {
    Sun,
    Moon,
    Search,
    UserRound,
    SendHorizontal,
    Heart
  }
});

  3. Use the icon partial in any .hbs file.

    {{> "components/icon" name="heart" class="w-4 h-4" ariaLabel="Heart icon"}}

Shadcn UI CSS Variable Support

This starter supports shadcn-style design tokens (CSS variables):

  • Variables defined in assets/css/shadcn-variables.css.
  • Imported in assets/css/styles.css.
  • Includes :root variables for light mode and .dark variables for dark mode.
  • @theme inline mappings for Tailwind CSS 4 tokens.

Vite Plugin List

The following plugins are configured in vite.config.ts:

  • ghostHmrPlugin: watches Handlebars (.hbs) templates, invalidates module graph for Tailwind CSS v4, and triggers full browser reloads for Ghost CMS.
  • @tailwindcss/vite: compiles Tailwind CSS 4 during build and development.
  • vite-plugin-image-optimizer: optimizes image assets (jpg/png/webp/svg/avif) for maximum performance.
  • vite-plugin-zip-pack (production mode): creates a theme .zip archive ready for upload.

Scripts

  • pnpm dev — Starts Vite HMR dev server on port 5173 for live reloading inside Ghost templates.
  • pnpm build — Creates a production build and generates the theme ZIP file.
  • pnpm test — Tests the Ghost CMS v6 theme using the gscan CLI.
  • pnpm screenshot — Captures full-page screenshots of theme routes across desktop, tablet, and mobile viewports using Playwright and generates an HTML gallery (screenshots/index.html).

Licensing

This starter is released under the MIT License (see LICENSE.md). You are free to use it for personal, client, or commercial projects.