Paige

Powerful, pliable pixel perfection. An advanced Hugo theme. Try it out.

<picture> <source media="(prefers-color-scheme: dark)" srcset="https://github.com/willfaught/paige/raw/master/images/screenshot-dark.jpg"> <source media="(prefers-color-scheme: light)" srcset="https://github.com/willfaught/paige/raw/master/images/screenshot.jpg"> <img alt="Screenshot" src="https://github.com/willfaught/paige/raw/master/images/screenshot.jpg"> </picture>

Paige is designed to put your content front and center, avoiding the typical clutter. The look is seamless and smooth, scalable and readable, portable and efficient. The layout is minimal and responsive, using verticality and white space to delineate and highlight each part of the page. The implementation is flexible and extensible. It’s a versatile canvas that serves most needs.

Features

• Accessibility
• Atom feeds
• Authors
• Blog
• Bootstrap styles and icons
• Breadcrumbs
• Categories
• Code shortcode
• Customizable
• Dark color scheme
• Email shortcode
• Facebook sharing
• Figure shortcode
• Gallery shortcode
• Icon shortcode
• Image pixel densities
• Image shortcode
• Image size breakpoints
• Image thumbnails
• Internationalization
• Landing page
• Light color scheme
• Localizations
• Math typesetting
• Menu
• Minimal design
• Quote shortcode
• Responsive
• Right-to-left languages
• RSS feeds
• Safari and Firefox Reader View support
• Search
• Sections
• SEO
• Series
• Single column
• Table of contents
• Tab shortcode
• Tags
• Title links
• Twitter sharing
• Validated with PageSpeed and Validator
• Vimeo shortcode
• YouTube shortcode

Community

Get started by starring and watching the project.

If you find a problem or have a suggestion, please share it by creating an issue.

If you have a fix or improvement, please share it by creating a pull request.

If you make a customization or alteration, please share it by posting code or screenshots.

If you deploy a site, please share it by posting a link.

Setup

1. Install Hugo and Dart Sass:

   For Homebrew on Mac:

   $ brew install hugo sass/sass/sass
   

   For Chocolatey on Windows:

   $ choco install hugo-extended sass
   

   For Snap on Linux:

   $ sudo snap install dart-sass hugo
   

   Hugo must be the extended version, and at least version 0.141.0.

2. Create a site:

   $ hugo new site yoursite
   

3. Create a post:

   $ cd yoursite
   $ hugo new yourpost.md
   

4. Configure your module:

   $ sh
   $ cd yoursite
   $ hugo mod init github.com/youraccount/yoursite
   $ cat >>hugo.toml <<EOF
   [markup.highlight]
   noclasses = false
   style = "github"
   EOF
   

5. Configure the Paige module:

   $ sh
   $ cd yoursite
   $ hugo mod get github.com/willfaught/paige@latest
   $ cat >>hugo.toml <<EOF
   [[module.imports]]
   path = "github.com/willfaught/paige"
   EOF
   

6. Build and run the site for development:

   $ cd yoursite
   $ hugo server --buildDrafts
   

7. Build the site for production:

   $ cd yoursite
   $ hugo --environment production --minify
   

8. Update the Paige module:

   $ cd yoursite
   $ hugo mod get github.com/willfaught/paige@latest
   

Paige uses Semantic Versioning. The current major version is 0. From time to time, breaking changes are made. When you update Paige, you must test your site.

See Hugo's installation, getting started, and module guides for more information.

Kickoff

By default, everything is enabled, which is likely not what you want. See the minimal look section for ideas of what to disable.

By default, the page body spans its entire container, which spans most of the window. See the narrow look and narrow-and-wide look sections for ideas of how to customize the presentation.

The breadcrumb, collection, section, and page links are sufficient to browse any site, so you can safely disable the menu. However, for sites with only a couple handfuls of sections and pages at the root level, and without nested sections, the menu alone can be sufficient for all navigation. See the menu navigation only section for how to do that.

To change the favicon, see the override section.

To add analytics, put the code in yoursite/layouts/partials/paige/site-last.html. See the include section.

To add comments, put the code in yoursite/layouts/partials/paige/page-body-last-page.html. See the include section.

Configure

Parameters

There is a single parameter object with sensible defaults that can be overridden in site or page parameters:

[paige]

enable_math = false # Enables math typesetting for this page
exclude_feeds = false # Excludes this page from feeds
exclude_search = false # Excludes this page from search
style = "" # CSS included in a stylesheet for this page

[paige.alert]

message = "" # Markdown displayed before the page body for this page
type = "primary" # Bootstrap alert class for this page

[paige.feeds]

disable_link = false # Disables using the link parameter for the page URL
page_link = "⏎" # Link to the page with this text if the link parameter is set and disable_link is false

[paige.feeds.atom]

authors = []
# Example:
# [[paige.feeds.atom.authors]]
# email = "example@example.com"
# name = "John Doe"
# url = "https://github.com/account/project"
icon = "" # Example: "/icon.webp"
logo = "" # Example: "/logo.webp"

[paige.feeds.rss]

managing_editor = "" # Example: "example@example.com (John Doe)"
web_master = "" # Example: "example@example.com (John Doe)"

[paige.pages]

# Content
disable_authors = false
disable_collections = false
disable_date = false
disable_description = false
disable_edit = false
disable_history = false
disable_keywords = false
disable_next = false
disable_pages = false
disable_prev = false
disable_reading_time = false
disable_sections = false
disable_series = false
disable_title = false
disable_toc = false
disable_word_count = false

# Presentation
full_width = false # Whether the page body fills the page width
maximize_heading_levels = false # Whether to shift heading levels higher as much as possible
maximum_heading_level = 6 # The maximum heading level to shift heading levels to
minimize_heading_levels = false # Whether to shift heading levels lower as much as possible
minimum_heading_level = 2 # The minimum heading level to shift heading levels to
normalize_heading_levels = false # Whether to shift heading levels higher to fill heading level gaps

# Schema
base_schema = {} # JSON-LD schema that all page schemas override
# Example:
# [paige.pages.base_schema]
# isAccessibleForFree = true
# isFamilyFriendly = true
# [paige.pages.base_schema.publisher]
# "@type" = "Organization"
# name = "John Doe"
# url = "https://example.com"
disable_auto_schema = false # Disables the automatic JSON-LD schema generation
microdata = {} # Microdata non-property attributes (all except itemprop) for the web page
# Example:
# [paige.pages.microdata]
# itemid = "foo"
# itemref = "bar"
# itemscope = ""
# itemtype = "https://schema.org/Chapter
schemas = [] # JSON-LD schemas
# Example:
# [[paige.pages.schemas]]
# "@context" = "https://schema.org"
# "@type" = "Book"
# name = "My Book"
# url = "https://example.com"

[paige.site]

# Behavior
date_format = ":date_long" # Hugo date format
external_link_new_tab = false # Open external links in new tabs

# Content
disable_copyright = false
disable_credit = false
disable_description = false
disable_license = false
disable_title = false

# Navigation
disable_breadcrumbs = false
disable_menu = false

# Presentation
color = "#0d6efd" # Bootstrap primary color and theme color for Safari and Windows
color_scheme = "auto" # Must be "auto", "dark", or "light"
keyword_style = "text" # Must be "text" or "pills"
menu_style = "links" # Must be "links", "pills", "tabs", or "underline"

# Repository
edit_url = "" # Example: "https://github.com/account/project/edit/master/content/%s"
history_url = "" # Example: "https://github.com/account/project/commits/master/content/%s"

# Schema
base_schema = {} # JSON-LD schema that all site schemas override
# Example:
# [paige.site.base_schema]
# isAccessibleForFree = true
# isFamilyFriendly = true
# [paige.site.base_schema.publisher]
# "@type" = "Organization"
# name = "John Doe"
# url = "https://example.com"
schemas = [] # JSON-LD schemas
# Example:
# [[paige.site.schemas]]
# "@context" = "https://schema.org"
# "@type" = "Organization"
# name = "Acme"
# url = "https://example.com"

# Values
credit = '<a class="link-secondary text-decoration-none" href="https://github.com/willfaught/paige">Paige Theme</a>'
description = "" # Site description. Appears above the menu and below the site title. Used in feeds.
license = "" # Example: "CC BY 4.0 License"

[paige.subpages]

disable_authors = false
disable_date = false
disable_description = false
disable_keywords = false
disable_reading_time = false
disable_series = false
disable_summary = false
disable_title = false
disable_word_count = false

The parameter object is accessed in site parameters a