Hugo SmolWeb Theme

A lightweight Hugo theme following SmolWeb specifications with CSS Grade B compliance.

Features

• SmolWeb Compliant: Follows SmolWeb guidelines for lightweight, accessible web design
• CSS Grade B: Uses only essential and basic responsive CSS properties
• Hugo v0.146.0+ Compatible: Uses the new template system structure
• Multilingual: Full support for multiple languages with Hugo's i18n (ready for en, fr, es, pt, de, it, pl, nl, ru, ja, zh, ar, sv, no)
• Categories & Tags: Built-in taxonomy support with clean archive pages
• Pagination: Automatic pagination for posts, sections, and taxonomy pages
• Dark Mode: Automatic dark theme based on system preferences (prefers-color-scheme)
• Centralized Colors: Efficient color management using CSS selector grouping (3 foreground + 3 background colors)
• No JavaScript: Works perfectly without any client-side scripts
• Semantic HTML5: Proper use of semantic elements (header, main, nav, article, aside, footer)
• System Fonts Only: No web font loading - uses system font stacks
• RSS Feeds: Built-in RSS support for content syndication
• Accessible: Works with screen readers and text-only browsers
• Print Friendly: Optimized print styles included

SmolWeb Compliance

This theme adheres to SmolWeb principles:

✅ Readable Without CSS

The site remains fully functional and readable when CSS is disabled.

✅ CSS Grade B Only

Only uses properties from CSS Grade A and B:

• Grade A: Box model, typography, basic layout, backgrounds, lists
• Grade B: Media queries, max/min-width, inline-block, position: relative

No Grade C+ properties like flexbox, grid, transforms, animations, or filters.

✅ No JavaScript

The theme contains zero JavaScript. All functionality is HTML/CSS only.

✅ Semantic HTML

Uses proper HTML5 semantic elements following the SmolWeb HTML subset.

✅ System Fonts

No @font-face declarations. Uses system font stack for zero font loading overhead.

✅ Content Security Policy

Includes CSP meta tag: default-src 'self';

Requirements

• Hugo v0.146.0 or later (uses new template system)
• No other dependencies

Installation

As a Hugo Module (Recommended)

hugo mod init github.com/yourusername/yoursite
hugo mod get codeberg.org/smolweb/hugo-smolweb

Then add to your hugo.toml:

[module]
 [[module.imports]]
 path = "codeberg.org/smolweb/hugo-smolweb"

As a Git Submodule

cd your-hugo-site
git submodule add https://codeberg.org/smolweb/hugo-smolweb.git themes/hugo-smolweb

Then add to your hugo.toml:

theme = "hugo-smolweb"

Manual Installation

Clone or download this repository into your Hugo site's themes directory:

cd your-hugo-site/themes
git clone https://codeberg.org/smolweb/hugo-smolweb.git

Configuration

Basic Configuration

Create or update your hugo.toml:

baseURL = "https://example.org/"
title = "My SmolWeb Site"
theme = "hugo-smolweb"
defaultContentLanguage = "en"
[params]
 mainSections = ["posts"]
 description = "A lightweight website following SmolWeb specifications"
 subtitle = "Simple, fast, accessible"
copyright = "Content licensed under CC BY-SA 4.0"
[outputs]
 home = ["HTML", "RSS"]
 section = ["HTML", "RSS"]
[taxonomies]
 tag = "tags"
 category = "categories"

Multilingual Configuration

For multilingual sites:

defaultContentLanguage = "en"
# Always include language code in URL (e.g., /en/, /fr/)
defaultContentLanguageInSubdir = true
[languages]
 [languages.en]
 languageCode = "en"
 languageName = "English"
 weight = 1
 [[languages.en.menu.main]]
 name = "Home"
 url = "/"
 weight = 1
 [[languages.en.menu.main]]
 name = "Posts"
 url = "/posts/"
 weight = 2
 [languages.fr]
 languageCode = "fr"
 languageName = "Français"
 weight = 2
 title = "Mon site SmolWeb"
 [languages.fr.params]
 description = "Un site web léger suivant les spécifications SmolWeb"
 [[languages.fr.menu.main]]
 name = "Accueil"
 url = "/"
 weight = 1
 [[languages.fr.menu.main]]
 name = "Articles"
 url = "/posts/"
 weight = 2

Content Organization

Hugo automatically creates language-specific URLs:

content/
├── _index.en.md → /en/
├── _index.fr.md → /fr/
├── about.en.md → /en/about/
├── about.fr.md → /fr/about/
└── posts/
 ├── post1.en.md → /en/posts/post1/
 └── post1.fr.md → /fr/posts/post1/

Dark Mode

The theme automatically adapts to the user's system color scheme preference using the CSS @media (prefers-color-scheme: dark) query (CSS Grade B compliant).

Light mode colors:

• Primary text: #1e293b (dark slate)
• Muted text: #64748b (gray)
• Accent: #2563eb (blue)
• Backgrounds: #ffffff, #f8fafc, #e2e8f0

Dark mode colors:

• Primary text: #f8fafc (light)
• Muted text: #94a3b8 (light gray)
• Accent: #60a5fa (lighter blue for better contrast)
• Backgrounds: #0f172a, #1e293b, #334155

The dark mode is applied automatically when the user's system is set to dark mode - no configuration needed!

Categories and Tags

The theme includes full support for Hugo taxonomies (categories and tags):

Front Matter Example

---title:"My Post"date:2025年10月30日categories:["tutorials","guides"]tags:["hugo","smolweb","web-development"]---

Display

• Single posts: Categories and tags appear below the title with links to archive pages
• Archive pages: Clean list view matching the posts page layout (uses term.html template)
• Navigation: Tags are prefixed with # for visual distinction

Taxonomy Pages

Hugo automatically creates these pages:

• /categories/ - List of all categories
• /categories/tutorials/ - Posts in "tutorials" category
• /tags/ - List of all tags
• /tags/hugo/ - Posts tagged with "hugo"

Each taxonomy page includes an RSS feed link in the footer.

Pagination

The theme automatically paginates long lists of posts on section pages, taxonomy pages, and term pages. Pagination is implemented using Hugo's .Paginator method and only uses CSS Grade B properties.

Configuration

Control the number of posts per page in hugo.toml:

[pagination]
 pagerSize = 10 # Number of posts per page (default: 10)

Features

• Automatic display: Pagination controls only appear when there's more than one page
• SmolWeb compliant: Simple HTML with CSS Grade B styling
• Navigation: Previous/Next buttons and page numbers
• Current page indicator: Bold styling for the current page
• SEO friendly: Uses proper rel="prev" and rel="next" attributes

The pagination component is styled to match the theme's minimal aesthetic and works perfectly without JavaScript.

Customization

Custom CSS

To add custom CSS while maintaining SmolWeb compliance:

1. Create static/css/custom.css in your site
2. Only use Grade A and B properties

If this file exists, it is automatically included.

Favicon

Place your favicon files in static/:

• static/favicon.ico (16x16 or 32x32)
• static/favicon.png (32x32 or larger)
• static/favicon.gif (32x32 or larger)

Keep files small (under 5KB recommended). Only existing favicons are included.

Menu Configuration

Menus are configured in hugo.toml:

[[menu.main]]
 name = "Home"
 url = "/"
 weight = 1
[[menu.main]]
 name = "About"
 url = "/about/"
 weight = 2

Template Structure (Hugo v0.146.0+)

This theme uses the new Hugo template system:

layouts/
├── baseof.html # Base template
├── home.html # Homepage (not index.html!)
├── page.html # Single pages (used for blog posts)
├── single.html # Fallback for pages
├── list.html # Section lists (used by posts, also copied to term.html)
├── section.html # Section lists
├── taxonomy.html # Taxonomy pages
├── term.html # Term pages (categories/tags archives)
├── 404.html # 404 error page
├── _partials/ # Partials (underscore!)
│ ├── head.html
│ ├── header.html
│ ├── footer.html
│ ├── nav.html
│ └── language-switcher.html
└── _markup/ # Render hooks
 └── render-link.html

Note: This follows Hugo v0.146.0+ conventions:

• No _default/ folder
• _partials/ with underscore
• home.html instead of index.html
• page.html has priority over single.html for blog posts
• term.html provides consistent styling for taxonomy archives

Translation Strings

The theme includes English and French translations. To add more languages:

1. Create i18n/[lang].toml in your site
2. Copy strings from themes/hugo-smolweb/i18n/en.toml
3. Translate the values

Example strings:

• recent_posts
• all_terms
• rss_feed
• back_home
• 404_title
• 404_message

Testing SmolWeb Compliance

Test Without CSS

In your browser:

• Firefox: View → Page Style → No Style
• Chrome: DevTools → Coverage → Disable CSS

The site should remain fully functional.

Test with Text Browsers

# Lynx
lynx http://localhost:1313
# w3m
w3m http://localhost:1313
# Links
links http://localhost:1313

Test with Old Browsers

• Netsurf
• Dillo
• Mosaic (if you're adventurous!)

Validate HTML

Use the W3C Validator or SmolWeb Validator.

Check CSS Grade

Review static/css/main.css against the CSS Grading Guide.

Development

Running the Example Site

The exampleSite is located inside the theme directory. To run it:

cd exampleSite
hugo server --themesDir ../.. -D

The --themesDir ../.. flag tells Hugo to look for themes two directories up, which points to the theme's parent directory.

Visit http://localhost:1313

Building for Production

hugo --minify

SmolWeb Resources

• SmolWeb Guidelines
• CSS Grading Specification
• HTML Subset
• SmolWeb Validator

License

This theme is released under the Creative Commons Attribution-ShareAlike 4.0 International License (CC-BY-SA 4.0). See LICENSE file for details.

Contributing

Contributions are welcome! Please ensure:

1. CSS Grade B compliance: Only use Grade A and B properties
2. No JavaScript: Keep the theme script-free
3. Semantic HTML: Use proper HTML5 elements
4. Accessibility: Test with screen readers and text browsers
5. Hugo v0.146.0+ compatibility: Follow new template system

Credits

• Built for Hugo
• Follows SmolWeb specifications
• Inspired by the movement for a simpler, more accessible web

Support

• Report issues
• Hugo documentation
• SmolWeb community

Remember: The best SmolWeb sites are simple, fast, and accessible to everyone, regardless of their device or connection speed.