Clean Theme Documentation

🗒️

A minimal, clean theme for Marmite static site generator.

Features

  • Clean Design: Minimal, distraction-free layout
  • Responsive: Works great on desktop, tablet, and mobile
  • Dark Mode: Automatic dark mode based on system preference
  • Fast: Lightweight CSS and JavaScript
  • Accessible: Semantic HTML and keyboard navigation
  • SEO Ready: Proper meta tags and structured data
  • Search: Built-in search functionality (when enabled)

Customization

Colors

You can easily customize the theme colors by editing the CSS custom properties in static/style.css:

:root {
  --primary-color: #2c5aa0;        /* Main brand color */
  --secondary-color: #f8f9fa;      /* Background accents */
  --text-color: #333;              /* Main text color */
  --link-color: #2c5aa0;           /* Link color */
  --background-color: #fff;        /* Page background */
}

Layout

The theme uses a flexible layout system. You can customize:

  • Header: Edit templates/base.html or create content/_header.md
  • Footer: Edit templates/base.html or create content/_footer.md
  • Sidebar: Create content/_sidebar.md
  • Hero Section: Create content/_hero.md

Typography

The theme includes the accessible Atkinson Hyperlegible font for better readability:

@font-face {
  font-family: "Atkinson Hyperlegible";
  src: url("./Atkinson-Hyperlegible-Regular-102.woff");
}

It also uses system fonts as fallback for fast loading:

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;

You can change the font settings in static/style.css or add additional web fonts.

JavaScript

The theme includes minimal JavaScript for:

  • Search overlay functionality
  • Smooth scrolling for anchor links
  • External link indicators
  • Mobile menu support

Configuration

Required Marmite Settings

# marmite.yaml
name: "Your Site Name"
tagline: "Your site description"
enable_search: true  # For search functionality

Optional Settings

# Enhanced footer
footer: |
  <p>&copy; 2025 Your Name. All rights reserved.</p>
  <p><a href="/about.html">About</a> | <a href="/contact.html">Contact</a></p>

# Custom menu
menu:
  - ["Home", "index.html"]
  - ["About", "about.html"]
  - ["Tags", "tags.html"]
  - ["Archive", "archive.html"]

# Fediverse verification (adds rel="me" link)
extra:
  fediverse_verification: "https://mastodon.social/@yourusername"

Markdown Fragments

The theme supports these optional Markdown fragments:

  • _announce.md - Site-wide announcement bar
  • _header.md - Custom header content
  • _hero.md - Hero section on homepage
  • _sidebar.md - Sidebar content
  • _footer.md - Custom footer content
  • _comments.md - Comments system integration
  • _htmlhead.md - Custom HTML in <head>
  • _htmltail.md - Custom HTML before </body>

Content Structure

Posts

Posts should include front matter for best results:

---
title: "Your Post Title"
date: 2025-07-21
authors: ["Your Name"]
tags: ["tag1", "tag2"]
description: "Brief description for SEO"
banner_image: "media/your-image.jpg"
---

Your post content here...

Pages

Pages are similar but typically don't have dates:

---
title: "About"
description: "About this website"
---

About page content...

Assets Included

The theme comes with these pre-built assets:

  • Atkinson-Hyperlegible-Regular-102.woff: Accessible web font for better readability
  • avatar-placeholder.png: Default avatar image for authors
  • favicon.ico: Site favicon
  • logo.png: Default site logo placeholder
  • robots.txt: SEO robots file
  • script.js: Theme JavaScript functionality
  • search.js: Search functionality (provided by Marmite)
  • style.css: Complete theme stylesheet

Development

To customize the theme further:

  1. CSS: Edit static/style.css
  2. JavaScript: Edit static/script.js
  3. Templates: Modify files in templates/
  4. Assets: Replace or add images, fonts, etc. in static/
  5. Fonts: The theme includes Atkinson Hyperlegible font, or you can add your own

Browser Support

The theme supports all modern browsers:

  • Chrome 60+
  • Firefox 60+
  • Safari 12+
  • Edge 79+

Performance

The theme is optimized for performance:

  • CSS: Single file with CSS custom properties for easy theming
  • JavaScript: Minimal, focused functionality
  • Web font: Single Atkinson Hyperlegible font file (~40KB) for accessibility
  • System fonts: Used as fallback for fast loading
  • No external dependencies (except for search.js from Marmite)
  • Embedded assets: All theme files are embedded in Marmite binary

Accessibility

The theme follows accessibility best practices:

  • Semantic HTML structure
  • Keyboard navigation support
  • High contrast colors
  • Screen reader friendly
  • Focus indicators

Theme Configuration (theme.json)

The theme includes a theme.json file that describes the theme and its capabilities:

{
  "name": "THEME_NAME",
  "version": "0.1.0",
  "author": "AUTHOR_NAME",
  "description": "THEME_DESCRIPTION",
  "marmite_version": ">=0.2.6",
  "extra_config_allowed": {
    "fediverse_verification": {
      "enabled": true,
      "required": false,
      "description": "Enable Fediverse Username Verification",
      "type": "string",
      "example": "https://mastodon.social/@username"
    }
  }
}

This configuration allows the theme to:

  • Define supported extra configuration options
  • Specify minimum Marmite version requirements
  • Document theme metadata and features

Embedded Theme Template

As of Marmite 0.2.6+, this theme template is embedded directly in the Marmite binary. This means:

  • Always available: No need to download or locate template files
  • Version consistency: Template matches your Marmite version exactly
  • Fast theme creation: --start-theme extracts embedded files instantly
  • No external dependencies: Everything needed is included

License

This theme is released under the AGPL License, same as Marmite.

Comentários