BaseTheme

A Jekyll remote theme, crafted as a lean foundation for static sites on GitHub Pages.

For examples of building on this foundation, see the demo site and its source.

Features

• 🪶 Minimal, no-bloat foundation, no JavaScript required
• ✍️ Write naturally - no YAML front matter needed
  • 📄 Page titles from first heading
  • 🎯 Automatic layout detection
• 🎨 Flexible styling options
  • 🌓 Dark mode support
  • 🖨️ Print-friendly layouts
• 🌐 Responsive and accessible by design
  • 📱 Mobile-first approach
  • ♿️ WCAG compliance built-in
• 🔍 SEO-ready with metadata and sitemaps

Demo & Template

See it in action:

• Live Demo - shows both basic usage and optional features
• Demo Source - includes additional blog features

Quick Start

If you prefer to start from scratch rather than using the template:

1. Configure your _config.yml:

   # Theme Settings
   remote_theme: "ChristopherA/BaseTheme@main"
   
   # Required Plugins
   plugins:
     - jekyll-remote-theme         # Required for remote themes
     - jekyll-seo-tag             # Required for SEO meta tags
     - jekyll-sitemap             # Required for search engines
     - jekyll-titles-from-headings # Required for automatic page titles
     - jekyll-default-layout      # Required for automatic layouts
   
   # Site Settings
   title: "Your Site Title"
   description: "Your site description"
   url: "https://yourusername.github.io"  # Root URL where site will be hosted
   baseurl: "/your-repo-name"  # Leave empty if hosting at root URL
   
   # Optional Settings
   navigation:
     - title: Home
       url: /
     - title: About
       url: /about/
   date_format: "%B %d, %Y"  # Default date format for posts
   
   # Jekyll Settings
   markdown: kramdown
   collections:
     pages:
       output: true

2. Create your home page index.md:

   ---
   description: "Optional SEO description"  # Only if needed
   ---
   
   # Welcome to Your Site
   
   Your content starts here!

3. Create a sample post in _posts/YYYY-MM-DD-title.md (optional - only if you want blog features):

   ---
   date: YYYY-MM-DD              # Required for posts
   description: "Optional SEO description"
   ---
   
   # Your First Post
   
   Your post content here.

4. Deploy to GitHub Pages: Follow GitHub's official guide to Creating a GitHub Pages site. Make sure to:

   • Create a new repository
   • Push your files to the appropriate branch (usually main or gh-pages)
   • Enable GitHub Pages in your repository settings

5. Optional: Run Jekyll locally: SIDENOTE: Personally, I rarely do this, and instead rely on the free GitHub Pages infrastructure.

   To run Jekyll locally, you'll need install Ruby and Jekyll for your operating system:

   • macOS: brew install ruby jekyll
   • Ubuntu/Debian: sudo apt install ruby-full jekyll
   • Windows: See Jekyll on Windows

   Then run:

   bundle install   # Install required gems
   jekyll serve     # Start local server at http://localhost:4000

   More details for running Jekyll locally are at the official Jekyll Installation Guide.

Layouts

BaseTheme uses automatic layout detection based on content location:

1. Posts in _posts/ → post layout
2. Files named index.md → home layout
3. Other .md files → page layout
4. .html files → default layout

You can override any automatic layout by specifying it in front matter:

---
layout: custom-layout
---

Front Matter

Required only for blog entries in _posts:

---
date: YYYY-MM-DD   # Required for blog posts
---

Optional front matter:

---
description: "SEO description"  # Optional: recommended for better SEO
permalink: /custom-url/         # Optional: custom URL path instead of filename-based path
title: "Override Title"         # Optional: only if different from first H1 heading
layout: "custom"                # Optional: use specific layout instead of automatic one 
---

License

This theme is released under CC0 ("No Rights Reserved"). You can copy, modify, distribute and use the theme without attribution or permission. For more details, see the LICENSE file.

Author

Created by Christopher Allen (GitHub @ChristopherA)