Minimal Hugo Theme for Modern AsciiDoc-based Blogs

This theme is designed for developers and STEAM audiences who value simplicity, modern standards, and minimal dependencies. It is a humble fork of antora-default-ui-hugo-theme with a focus on building a clean, professional, and blogging-friendly platform.

Key Principles:

• Minimalism: No fancy frameworks, preprocessors, or bloat. Only barebones CSS, HTML, and limited JavaScript.
• Modern Standards: Uses modern CSS, HTML, and JavaScript features. No support for outdated browsers (e.g., Internet Explorer).
• No Preprocessing: Avoids TailWindCSS, SCSS, or JavaScript frameworks. No post/preprocessing for CSS or JS.
• Simplicity: Only adds JavaScript when absolutely necessary, and keeps it minimal.

---

Antora Default UI Theme for Hugo is based on the Antora default UI, with full support for Asciidoctor. (Demo)

Features

• Asciidoc Support: Write content in Asciidoc, rendered by Hugo and Asciidoctor.
• Responsive Design: Mobile-friendly layouts using modern CSS.
• Beautiful, Professional Typography: Web fonts and CSS for clean, immersive reading on all devices.
• Syntax Highlighting: Prefer Rouge, with optional highlight.js support via simple CSS/JS includes.
• Minimal Navigation & Pagination: Accessible, simple navigation and pagination.
• Internationalization: Uses Hugo’s standard i18n features, nothing custom.

Prerequisites

Before starting, ensure you have:

• Installed Hugo
• Created a new site
• Installed Asciidoctor

Installation

TODO: Add demo with the modern Hugo module workflow.

Configuration

Configure Asciidoctor attributes in your site's config.toml:

[markup]
  [markup.asciidocext]
    [markup.asciidocext.attributes]
      "icons" = "font"
      "source-highlighter" = "rouge"
  [markup.highlight]
    codeFences = true

Optionally, set a description and keywords for the home page:

[params]
  description = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
  keywords = ["foo", "bar"]

Optionally, set a copyright message and year for the footer:

copyright = "<name>. All rights reserved."

[params]
  since = <year>

Optionally, set a URL for the Edit this page feature:

[params]
  editThisPage = "https://github.com/organization/repository/edit/main/content/"

Customization

You can add custom CSS files by specifying their paths (relative to assets/) in your site configuration:

[params]
custom_css = ["carrousel.css", "profile.css"]

Syntax Highlighting

This theme uses Rouge by default, or highlight.js for syntax highlighting. The included highlight.js supports common languages and AsciiDoc. To add more languages, download a custom package and place it in assets/js/vendor/highlight.pack.js.

Theme Structure

• assets/ — CSS, fonts, and JavaScript (plain, modern, minimal)
• layouts/ — Hugo templates for pages, partials, and base layouts
• static/ — Static files (images, fonts) served as-is
• archetypes/ — Default content templates (Asciidoc)
• i18n/ — Language files for Hugo’s i18n support

Contribution Guidelines

• Stick to the project philosophy: minimal, modern, and simple
• Do not introduce frameworks, preprocessors, or unnecessary dependencies
• Use plain CSS, HTML, and JavaScript. Only add JS if required for usability
• Organize code according to the theme structure above
• Test changes locally using Hugo’s built-in server
• Reference previous Copilot PRs for context on implemented features

Development & Testing

• Install Hugo and Asciidoc (see above)
• Run hugo server to preview changes locally
• Keep i18n simple: use Hugo’s language files
• Submit pull requests with clear descriptions and reference relevant issues or previous PRs

Out of Scope

• No support for old browsers (e.g., IE)
• No advanced build tools or dependency managers (e.g., nix flake optional, not required)
• No custom i18n or accessibility frameworks beyond Hugo’s basics
• No fancy CSS processors or JavaScript frameworks

---

License

Released under the Mozilla Public License, Version 2.0 (MPL-2.0).

Acknowledgements

• Dan Allen, Asciidoctor Project Lead & Antora Project Co-Lead
• Basil Crow, Antora Default UI Theme for Hugo Project author, lead and owner.