Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/willfaught/paige

Powerful, pliable pixel perfection. An advanced Hugo theme.
https://github.com/willfaught/paige

blog blog-theme blogging blogs hugo hugo-blog hugo-blog-theme hugo-module hugo-site hugo-starter hugo-theme module theme

Last synced: 9 months ago
JSON representation

Powerful, pliable pixel perfection. An advanced Hugo theme.

Awesome Lists containing this project

README 

          
# Paige



Powerful, pliable pixel perfection.

An advanced Hugo theme.

[Try it out.](https://willfaught.com/paige)



    

    

    Screenshot



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](https://pagespeed.web.dev/report?url=https%3A%2F%2Fwillfaught.com%2Fpaige%2F&form_factor=desktop) and [Validator](https://validator.w3.org/nu/?doc=https%3A%2F%2Fwillfaught.com%2Fpaige%2F)

- Vimeo shortcode

- YouTube shortcode



## Community



Get started by [starring](https://github.com/willfaught/paige/stargazers)

and [watching](https://github.com/willfaught/paige/watchers) the project.



If you find a problem or have a suggestion,

please share it by [creating an issue](https://github.com/willfaught/paige/issues/new).



If you have a fix or improvement,

please share it by [creating a pull request](https://github.com/willfaught/paige/compare).



If you make a customization or alteration,

please share it by [posting code or screenshots](https://github.com/willfaught/paige/discussions/8).



If you deploy a site,

please share it by [posting a link](https://github.com/willfaught/paige/discussions/12).



## Setup



1. Install [Hugo](https://gohugo.io/installation/) and [Dart Sass](https://github.com/sass/dart-sass):



    For Homebrew on Mac:



    ```sh

    $ brew install hugo sass/sass/sass

    ```



    For Chocolatey on Windows:



    ```sh

    $ choco install hugo-extended sass

    ```



    For Snap on Linux:



    ```sh

    $ sudo snap install hugo

    ```



    Hugo must be the extended version, and at least version v0.141.0.



2. Create a site:



    ```sh

    $ hugo new site yoursite

    ```



3. Create a post:



    ```sh

    $ cd yoursite

    $ hugo new yourpost.md

    ```



4. Configure your module:



    ```sh

    $ cd yoursite

    $ hugo mod init github.com/youraccount/yoursite

    $ cat >>hugo.toml <>hugo.toml <

    
lang


    
Optional. Position 0. String. Chroma language code. Default is "plaintext".


    
options


    
Optional. String. Hugo highlight options.


    
unescape


    
Optional. Boolean. Whether to reverse the HTML escaping in the body. Useful for when the request shortcode is used in the body.



Body: Required. String. The code.



### Email



The `paige/email` shortcode hides e-mail addresses from robots.



Parameters:





    
address


    
Required. Position 0. String. The e-mail address.





Body: Required. String. Markdown. The content.



### Figure



The `paige/figure` shortcode provides a figure.



Parameters:





    
caption


    
Optional. Position 0. String. Markdown. Descriptive text below the content.


    
float


    
Optional. String. Float to one side of its container. Must be "start" or "end".


    
height


    
Optional. String. CSS value. Total height.


    
horizontal


    
Optional. String. Horizontal alignment. Must be "start", "center", or "end". Default is "center".


    
maxwidth


    
Optional. String. CSS value. Maximum total width.


    
number


    
Optional. Integer or string. Figure number. Displayed with the caption.


    
numbered


    
Optional. Boolean. Number the figure automatically. Displayed with the caption.


    
vertical


    
Optional. String. Vertical alignment. Must be "start", "center", or "end". Default is "center".


    
width


    
Optional. String. CSS value. Total width.





Body: Required. String. Markdown. The content.



### Gallery



The `paige/gallery` shortcode provides an arrangement of images.



Parameters:





    
align


    
Optional. String. Cross axis alignment. Must be "baseline", "center", "end", "start", or "stretch".


    
breakpoints


    
Optional. Boolean. Whether to generate copies of the image sized to each Bootstrap breakpoint. Must not use with densities. Only applies to raster images.


    
class


    
Optional. String. Image class. Merged with implementation classes.


    
densities


    
Optional. String. Float numbers suffixed with an "x", delimited by spaces. The pixel densities of the image to generate. There must be at least two. The largest density matches the original image. Examples are "1x 2x", "1x 1.5x 2x 2.5x 3x", and "0.5x 1.33x 6x 10x". Must not use with breakpoints. Only applies to raster images.


    
fetchpriority


    
Optional. String. Must be "high" or "low".


    
height


    
Optional. String. CSS value. Image height.


    
images


    
Optional. Position 0. String. Page, site, or remote images glob. Default is all image page resources.


    
justify


    
Optional. String. Main axis space distribution. Must be "around", "between", "center", "end", "evenly", or "start".


    
linked


    
Optional. Boolean or string. Wraps the image in an anchor. If it is a string, it is Hugo image processing methods and options, mixed together, for the linked image. If no method is specified, resize is used. If no image dimensions are specified, the originals are used. If it is default, the default options are used. If it is a Boolean, it is unprocessed. Must be a Boolean for vector images.


    
loading


    
Optional. String. Must be "eager" (default) or "lazy".


    
maxheight


    
Optional. String. CSS value. Maximum image height.


    
maxwidth


    
Optional. String. CSS value. Maximum image width.


    
process


    
Optional. String. Hugo image processing methods and options, mixed together, for the displayed image. If no method is specified, resize is used. If no image dimensions are specified, the originals are used. If it is "default", the default options are used. Only applies to raster images.


    
style


    
Optional. String. CSS. Image style. Merged with implementation styles.


    
type


    
Optional. String. Type of layout. Must be "grid" or "rows" (default).


    
width


    
Optional. String. CSS value. Image width.





Body: Optional. String. HTML. The images.



### Icon



The `paige/icon` shortcode provides a web font icon.



Parameters:





    
class


    
Required. Position 0. String. Container class. Example: "bi bi-github".


    
title


    
Optional. String. The screen reader description and anchor title. Example: "GitHub".


    
url


    
Optional. String. URL. Example: "https://github.com/account/project". E-mails in URLs with a mailto: scheme are protected from web crawlers.





Body: None.



### Image



The `paige/image` shortcode provides an image.



Parameters:





    
alt


    
Optional. String. Plain text. Image alt.


    
breakpoints


    
Optional. Boolean. Whether to generate copies of the image sized to each Bootstrap breakpoint. Must not use with densities, sizes, or srcset. Only applies to raster images.


    
class


    
Optional. String. Class attribute value.


    
densities


    
Optional. String. Float numbers suffixed with an "x", delimited by spaces. The pixel densities of the image to generate. There must be at least two. The largest density matches the original image. Examples are "1x 2x", "1x 1.5x 2x 2.5x 3x", and "0.5x 1.33x 6x 10x". Must not use with breakpoints, sizes, or srcset. Only applies to raster images.


    
fetchpriority


    
Optional. String. Must be "high" or "low".


    
height


    
Optional. String. CSS value. Image height.


    
link


    
Optional. String. URL. Image link. Must not use with linked.


    
linked


    
Optional. Boolean or string. Wraps the image in an anchor. If it is a string, it is Hugo image processing methods and options, mixed together, for the linked image. If no method is specified, resize is used. If no image dimensions are specified, the originals are used. If it is "default", the default options are used. If it is a Boolean, it is unprocessed. Must be a Boolean for vector images. Must not use with link.


    
loading


    
Optional. String. Must be "eager" (default) or "lazy".


    
maxheight


    
Optional. String. CSS value. Image maximum height.


    
maxwidth


    
Optional. String. CSS value. Image maximum width.


    
process


    
Optional. String. Hugo image processing methods and options, mixed together, for the displayed image. If no method is specified, resize is used. If no image dimensions are specified, the originals are used. If it is "default", the default options are used. Only applies to raster images.


    
sizes


    
Optional. String. Image sizes. Must not use with breakpoints or densities.


    
src


    
Required. Position 0. String. URL. Image source.


    
srcset


    
Optional. String. Image srcset. Must not use with breakpoints or densities.


    
style


    
Optional. String. CSS. Image style. Merged with implementation styles.


    
title


    
Optional. String. Plain text. Image title.


    
width


    
Optional. String. CSS value. Image width.





Body: None.



### Quote



The `paige/quote` shortcode provides a quotation.



Parameters:





    
cite


    
Optional. String. Markdown. Citation.





Body: Required. String. Markdown. The quotation.



### Request



The `paige/request` shortcode provides the content for a URL.



Parameters:





    
method


    
Optional. String. HTTP method. Default is "get".


    
url


    
Required. String. URL.





Body: None.



### Tabs



The `paige/tabs` shortcode provides tab buttons and tab panes.

It must contain one `paige/tabs/buttons` shortcode, and then one `paige/tabs/panes` shortcode.



Parameters: None.



Body: Required. String. HTML. The tab buttons and tab panes.



The `paige/tabs/buttons` shortcode provides tab buttons.

It must contain one or more `paige/tabs/button` shortcodes.

Each `paige/tabs/button` shortcode corresponds to the `paige/tabs/pane` shortcode in the same position.



Parameters: None.



Body: Required. String. HTML. The tab buttons.



The `paige/tabs/button` shortcode provides a tab button.



Parameters: None.



Body: Required. String. Markdown. The tab button content.



The `paige/tabs/panes` shortcode provides tab panes.

It must contain one or more `paige/tabs/pane` shortcodes.

Each `paige/tabs/pane` shortcode corresponds to the `paige/tabs/button` shortcode in the same position.



Parameters: None.



Body: Required. String. HTML. The tab panes.



The `paige/tabs/pane` shortcode provides a tab pane.



Parameters: None.



Body: Required. String. Markdown. The tab pane content.



### Vimeo



The `paige/vimeo` shortcode provides a Vimeo video.



Parameters:





    
autopause


    
Optional. Boolean. Enable playing more than one Vimeo video on the same page. Default is true.


    
autoplay


    
Optional. Boolean. Autoplay the video. Default is false.


    
background


    
Optional. Boolean. Autoplay the video. Hide the controls. Loop the video. Mute the video. Default is false.


    
byline


    
Optional. Boolean. Show the author. Default is configured per video.


    
color


    
Optional. String. Hex code. Control color. Default is "00adef".


    
controls


    
Optional. Boolean. Show the controls. Default is true.


    
description


    
Optional. String. Plain text. Screen reader content. Default is "Vimeo video".


    
dnt


    
Optional. Boolean. Do not track session data. Default is false.


    
fullscreen


    
Optional. Boolean. Enable full screen. Default is true.


    
height


    
Optional. String. CSS value. Video height.


    
keyboard


    
Optional. Boolean. Enable keyboard input. Default is true.


    
loop


    
Optional. Boolean. Loop the video. Default is false.


    
maxheight


    
Optional. String. CSS value. Video maximum height.


    
maxwidth


    
Optional. String. CSS value. Video maximum width.


    
muted


    
Optional. Boolean. Mute the video. Default is false.


    
pip


    
Optional. Boolean. Show the picture-in-picture control. Default is false.


    
playsinline


    
Optional. Boolean. Play inline instead of full screen on mobile devices. Default is true.


    
portrait


    
Optional. Boolean. Show the author's profile image. Default is configured per video.


    
quality


    
Optional. String. The resolution. Must be "auto", "240p", "360p", "540p", "720p", "1080p", "2k", or "4k". Default is "auto".


    
speed


    
Optional. Boolean. Show the speed controls. Default is false.


    
texttrack


    
Optional. String. Language code and optionally a locale code (e.g. "en", "en-US"). Use the corresponding subtitles. Default is false.


    
time


    
Optional. String. Duration (e.g. "0m", "1m2s"). Start time. Default is "0m".


    
title


    
Optional. Boolean. Show the title. Default is configured per video.


    
transparent


    
Optional. Boolean. Use a transparent background instead of a black one. Default is true.


    
video


    
Optional. Position 0. String. Video ID.


    
width


    
Optional. String. CSS value. Video width.





Body: None.



See [Vimeo documentation](https://vimeo.zendesk.com/hc/en-us/articles/360001494447-Player-parameters-overview) for more detail.



### YouTube



The `paige/youtube` shortcode provides a YouTube video.



Parameters:





    
autoplay


    
Optional. Boolean. Automatically play the video.


    
controls


    
Optional. Boolean. Show video controls. Default is true.


    
description


    
Optional. String. Plain text. Screen reader content. Default is "YouTube video".


    
end


    
Optional. Integer. Elapsed seconds. Stop the video here.


    
fullscreen


    
Optional. Boolean. Enable full screen. Default is true.


    
height


    
Optional. String. CSS value. Video height.


    
list


    
Optional. String. Playlist ID.


    
loop


    
Optional. Boolean. Loop the video.


    
maxheight


    
Optional. String. CSS value. Video maximum height.


    
maxwidth


    
Optional. String. CSS value. Video maximum width.


    
mute


    
Optional. Boolean. Mute the video.


    
start


    
Optional. Integer. Elapsed seconds. Start the video here.


    
video


    
Optional. Position 0. String. Video ID.


    
width


    
Optional. String. CSS value. Video width.





Body: None.



## Customize



### Include



Files can be included in many places in HTML.



| If this file exists in your site                | It is included at                |

| ------------------------------------------------| ---------------------------------|

| `layouts/partials/paige/body-first.html`        | The beginning of the body        |

| `layouts/partials/paige/body-last.html`         | The ending of the body           |

| `layouts/partials/paige/head-first.html`        | The beginning of the head        |

| `layouts/partials/paige/head-last.html`         | The ending of the head           |

| `layouts/partials/paige/page-body-first.html`   | The beginning of the page body   |

| `layouts/partials/paige/page-body-last.html`    | The ending of the page body      |

| `layouts/partials/paige/page-first.html`        | The beginning of the page        |

| `layouts/partials/paige/page-footer-first.html` | The beginning of the page footer |

| `layouts/partials/paige/page-footer-last.html`  | The ending of the page footer    |

| `layouts/partials/paige/page-header-first.html` | The beginning of the page header |

| `layouts/partials/paige/page-header-last.html`  | The ending of the page header    |

| `layouts/partials/paige/page-last.html`         | The ending of the page           |

| `layouts/partials/paige/site-first.html`        | The beginning of the site        |

| `layouts/partials/paige/site-footer-first.html` | The beginning of the site footer |

| `layouts/partials/paige/site-footer-last.html`  | The ending of the site footer    |

| `layouts/partials/paige/site-header-first.html` | The beginning of the site header |

| `layouts/partials/paige/site-header-last.html`  | The ending of the site header    |

| `layouts/partials/paige/site-last.html`         | The ending of the site           |



There are kind variants of include files that are included only when the file kind matches the page kind.



| If this file exists in your site               | It is included when         |

| -----------------------------------------------| ----------------------------|

| `layouts/partials/paige/[PLACE]-home.html`     | The page kind is "home"     |

| `layouts/partials/paige/[PLACE]-page.html`     | The page kind is "page"     |

| `layouts/partials/paige/[PLACE]-section.html`  | The page kind is "section"  |

| `layouts/partials/paige/[PLACE]-taxonomy.html` | The page kind is "taxonomy" |

| `layouts/partials/paige/[PLACE]-term.html`     | The page kind is "term"     |



Above, the place placeholder must be "body-first", "body-last", "head-first", etc.



Kind variants are included right after their counterpart non-kind variant.



The argument for the templates is the page.



### Override



Most code is in partial templates that the layout templates use.

Code can be added, changed, or removed easily by overriding the corresponding layout or partial template.



For example, `layouts/_default/list.html` and `layouts/_default/single.html` include `layouts/partial/paige/page.html`.

`layouts/partial/paige/page.html` includes `layouts/partial/paige/page-header.html`.

To change the page title for those layout templates, change `layouts/partial/paige/page-header.html`.



To change the page title for `layouts/_default/single.html` only,

replace the inclusion of `layouts/partial/paige/page.html` in `layouts/_default/single.html` with its content,

then in that, replace the inclusion of `layouts/partial/paige/page-header.html` with its content,

then in that, change the page title.



To change the favicon, override these files:



- `static/apple-touch-icon.png`

- `static/favicon-96x96.png`

- `static/favicon.ico`

- `static/favicon.svg`

- `static/web-app-manifest-192x192.png`

- `static/web-app-manifest-512x512.png`



You can generate these favicon files [here](https://realfavicongenerator.net).



To change the syntax highlighting styles, override these files [with your own](https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css):



- `layouts/partials/paige/dark.css`

- `layouts/partials/paige/light.css`



### Extend



Use CSS selectors to extend the default styling.



Page identifiers:





    
#paige-page-alert


    
The page alert.


    
#paige-page-authors


    
The page authors.


    
#paige-page-collections


    
The page collections.


    
#paige-page-collections-header


    
The page collections header.


    
#paige-page-content


    
The page content.


    
#paige-page-date


    
The page date.


    
#paige-page-description


    
The page description.


    
#paige-page-edit


    
The page edit link.


    
#paige-page-file


    
The container of the page edit and history links.


    
#paige-page-footer


    
The page footer that contains the page edit, history, next, and previous links.


    
#paige-page-header


    
The page header that contains the page metadata and table of contents.


    
#paige-page-history


    
The page history link.


    
#paige-page-keywords


    
The page keywords.


    
#paige-page-next


    
The page next link.


    
#paige-page-pages


    
The page pages.


    
#paige-page-pages-header


    
The page pages header.


    
#paige-page-pagination


    
The pagination of subpages.


    
#paige-page-prev


    
The page previous link.


    
#paige-page-reading-time


    
The page reading time.


    
#paige-page-sections


    
The page sections.


    
#paige-page-sections-header


    
The page sections header.


    
#paige-page-series


    
The page series.


    
#paige-page-siblings


    
The container of the page next and previous links.


    
#paige-page-title


    
The page title.


    
#paige-page-toc


    
The page table of contents.


    
#paige-page-word-count


    
The page word count.





Site identifiers:





    
#paige-site-breadcrumbs


    
The site breadcrumbs.


    
#paige-site-copyright


    
The site copyright.


    
#paige-site-credit


    
The site credit.


    
#paige-site-description


    
The site description.


    
#paige-site-footer


    
The site footer that contains the site copyright, license, and credit.


    
#paige-site-header


    
The site header that contains the site title, description, menu, and breadcrumbs.


    
#paige-site-license


    
The site license.


    
#paige-site-menu


    
The site menu.


    
#paige-site-title


    
The site title.





Page classes:





    
.paige-page-keyword-category


    
A page category keyword.


    
.paige-page-keyword-tag


    
A page tag keyword.


    
.paige-page-keywords


    
The page keywords.





Subpage classes:





    
.paige-page


    
A page.


    
.paige-page-authors


    
The page authors.


    
.paige-page-date


    
The page date.


    
.paige-page-description


    
The page description.


    
.paige-page-reading-time


    
The page reading time.


    
.paige-page-series


    
The page series.


    
.paige-page-summary


    
The page summary.


    
.paige-page-title


    
The page title.


    
.paige-page-word-count


    
The page word count.





Page kind classes:





    
.paige-kind-home


    
The container of pages with kind "home".


    
.paige-kind-section


    
The container of pages with kind "section".


    
.paige-kind-page


    
The container of pages with kind "page".


    
.paige-kind-taxonomy


    
The container of pages with kind "taxonomy".


    
.paige-kind-term


    
The container of pages with kind "term".





Page status classes:





    
.paige-status-draft


    
The container of draft pages.


    
.paige-status-expired


    
The container of expired pages.


    
.paige-status-future


    
The container of future pages.


    
.paige-status-modified


    
The container of modified pages.


    
.paige-status-published


    
The container of published pages.


    
.paige-status-unpublished


    
The container of unpublished pages.





Shortcode classes:





    
.paige-shortcode-code


    
The container of paige/code shortcodes.


    
.paige-shortcode-email


    
The container of paige/email shortcodes.


    
.paige-shortcode-figure


    
The container of paige/figure shortcodes.


    
.paige-shortcode-gallery


    
The container of paige/gallery shortcodes.


    
.paige-shortcode-icon


    
The container of paige/icon shortcodes.


    
.paige-shortcode-image


    
The container of paige/image shortcodes.


    
.paige-shortcode-quote


    
The container of paige/quote shortcodes.


    
.paige-shortcode-vimeo


    
The container of paige/vimeo shortcodes.


    
.paige-shortcode-youtube


    
The container of paige/youtube shortcodes.





### Minimal look



By default, everything is shown.

If you want a more minimal look, try the following parameter values:



```toml

[paige.pages]

disable_authors = true

disable_date = true

disable_keywords = true

disable_next = true

disable_prev = true

disable_reading_time = true

disable_series = true

disable_toc = true

disable_word_count = true



[paige.subpages]

disable_authors = true

disable_date = true

disable_keywords = true

disable_reading_time = true

disable_series = true

disable_summary = true

disable_word_count = true

```



### Narrow look



By default, the content expands to fill the whole window.

This can result in very long lines, depending on the window width.

To use [the recommended line length of 66 characters](https://en.wikipedia.org/wiki/Line_length#Printed_text) (40rem),

try the following in `yoursite/hugo.toml`:



```toml

[params.paige]

style = """

#paige-page-content,

#paige-page-pages > * { margin-left: auto; margin-right: auto; max-width: 40rem; }

"""

```



### Narrow-and-wide look



By default, the content expands to fill the whole window.

This can result in very long lines, depending on the window width.

To use [the recommended line length of 66 characters](https://en.wikipedia.org/wiki/Line_length#Printed_text) (40rem)

for all content except media,

try the following in `yoursite/hugo.toml`:



```toml

[params.paige]

style = """

#paige-page-content,

#paige-page-pages > * { margin-left: auto; margin-right: auto; max-width: 40rem; }

#paige-page-content > img,

#paige-page-content > .paige-shortcode-image,

#paige-page-content > .paige-shortcode-vimeo,

#paige-page-content > .paige-shortcode-youtube { max-width: 100%; }

"""

```



### Menu navigation only



If you configure a menu, and intend for it to be sufficient for all navigation,

you should hide the breadcrumbs on every page,

and hide the collection, section, and page lists on the home page if you use the default home page layout.



To hide the breadcrumbs on every page,

try the following in `yoursite/hugo.toml`:



```toml

[params.paige.site]

disable_breadcrumbs = true

```



To hide the collection, section, and page lists on the home page,

try the following in `yoursite/content/_index.md`:



```toml

[params.paige.pages]

disable_collections = true

disable_pages = true

disable_sections = true

```



## Credits



- Photos by [Lanty](https://unsplash.com/@photos_by_lanty)

- Photo by [Sergey Pesterev](https://unsplash.com/photos/JV78PVf3gGI)



## Project



Copyright 2022 [Will Faught](https://willfaught.com).

Licensed under the [EUPL](https://spdx.org/licenses/EUPL-1.2.html).

Hosted at https://github.com/willfaught/paige.