hugo-PaperMod

mirrors/hugo-PaperMod

Fork 0

mirror of https://github.com/adityatelange/hugo-PaperMod.git synced 2023-12-21 10:22:58 +01:00

Table of Contents

ToC
Intro
Override theme template
Enable Social-Metadata and SEO
Failed to find a valid digest in the 'integrity' attribute for resource ... ?
Bundling Custom css with theme's assets
Custom Head / Footer
Add menu to site
Pin a Post
Adding Custom Favicon(s)
Centering image in markdown
Using Hugo's Syntax highlighter "chroma"
Search not working ?
Posts from only one folder/section visible on home page
References

Intro
Override theme template
Enable Social-Metadata and SEO
Failed to find a valid digest in the 'integrity' attribute for resource ... ?
Bundling Custom css with theme's assets
Custom Head / Footer
Add menu to site
Pin a Post
Adding Custom Favicon(s)
Centering image in markdown
Using Hugo's Syntax highlighter "chroma"
Posts from only one folder/section visible on home page?
References

Intro

We'll be using yml/yaml format for all examples down below, I recommend using yml over toml as it is easier to read.
You can find any YML to TOML converters if necessary.

Override theme template

By Hugo's Lookup Order, you can override any part of a theme that you want. The following is a quick example.

Let's say you wish the list was different. All you have to do is copy the list template:

your-site/themes/papermod/layouts/_defaults/list.html

And paste it under your own layouts folder:

your-site/layouts/_defaults/list.html

Then you're free to make any changes you want to the list. When Hugo builds your site, your copy of list.html will be used instead of the theme's list.html.

These include OpenGraph, Twitter Cards and Schema.

params:
  env: production

or set HUGO_ENV as "production" in system env-vars

Failed to find a valid digest in the 'integrity' attribute for resource ... ?

Read about How Subresource Integrity helps: Subresource_Integrity

Why was the asset not loading ? : How_browsers_handle_Subresource_Integrity

Solution:

Set the following in config.yml

params:
  assets:
    disableFingerprinting: true

Linked Issues:

Bundling Custom css with theme's assets

For adding custom css to be bundled inside one minimized css

Create folder in yout project directory as

.(site root)
├── config.yml
├── content/
├── theme/hugo-PaperMod/
└── assets/
    └── css/
        └── extended/  <---
            ├── custom_css1.css <---
            └── any_name.css   <---

All css files inside assets/css/extended will be bundled !

Note: blank.css is just the placeholder so that it doesn't break the theme when no files are present under assets/css/extended

Linked Issues:

Papermod Theme: How to add custom CSS?

Custom Head / Footer

Custom css/js can be added by way mentioned below.

.(site root)
├── config.yml
├── content/
├── theme/hugo-PaperMod/
└── layouts
    ├── partials
    │   ├── comments.html
    │   ├── extend_footer.html <---
    │   └── extend_head.html   <---
    └── robots.txt

Create a html page in directory structure as shown above.

Contents of extend_head.html will be added to head of page.

and contents of extend_footer.html will be added to bottom of page.

You can add menu entries which will appear in the header of every page.

To do so, add a menu section to your site's config.yml:

menu:
  main:
    - identifier: categories
      name: categories
      url: /categories/
      weight: 10
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: example
      name: example.org
      url: https://example.org
      weight: 30

name controls what will be displayed for the menu entry. url sets the URL that the entry points to. weight is used to control the positioning of entries.

For more information on menus, see the Hugo wiki page.

Pin a Post

Post can be pinned/ displayed top on the list by adding a weight=<num> var to page-variables

example:

---
title: "My Important post"
date: 2020-09-15T11:30:03+00:00
weight: 1
---

---
title: "My 2nd Important post"
date: 2020-09-15T11:30:03+00:00
weight: 2
---

Adding Custom Favicon(s)

We support the following paths under /static directory and can be added accordingly.

favicon.ico
favicon-16x16.png
favicon-32x32.png
apple-touch-icon.png
safari-pinned-tab.svg

Favicon(s) can be generated by Favicon.io

and can be simply put in /static folder.

Other way is to add favicon(s) NOT located in /static folder.

In site config add the following:

params:
  assets:
    favicon: "<link / absolute url>"
    favicon16x16:  "<link / absolute url>"
    favicon32x32:  "<link / absolute url>"
    apple_touch_icon:  "<link / absolute url>"
    safari_pinned_tab:  "<link / absolute url>"

absolute url means direct links to external resource: ex. https://web.site/someimage.png

example:

params:
  assets:
    favicon: "/favicon.ico"
    favicon16x16:  "/favicon-16x16.png"
    favicon32x32:  "/favicon-32x32.png"
    apple_touch_icon:  "/apple-touch-icon.png"
    safari_pinned_tab:  "/safari-pinned-tab.svg"

Centering image in markdown

Add #center after image to center align an image

![name](path/to/image.png#center)

When using figure shortcode

use align=center to center image with captions

ex.

{{< figure align=center src="image.jpg" >}}

Using Hugo's Syntax highlighter "chroma"

Disable Highlight.js in site config.yml

params:
  assets:
    disableHLJS: true

Set hugo's markdown styling in site config.yml

markup:
  highlight:
    # anchorLineNos: true
    codeFences: true
    guessSyntax: true
    lineNos: true
    # noClasses: false
    style: monokai

If you want lineNos: true, the background won't be proper. This will only work with noClasses: false or pygmentsUseClasses: true. Read Generate Syntax Highlighter CSS

Add the following to assets/css/extended/custom.css
```
.chroma {
  background-color: unset !important;
}
```
You can use, for ex.
```
hugo gen chromastyles --style dracula > assets/css/extended/dracula.css
```
More Info : Configure Markup - Highlight

Search not working ?

If you are using a CDN to server assets from a different domain, search would break

Why? Take a look at fastsearch.js#L35.

We fetch the index.json (where the search function looks for the keywords typed) one level up of the website search.min.js is hosted on.

We have used this insted of assigning baseURL so as to work with multilingual websites ex. example.com/fr/ and websites being placed under a subdirectory ex. example.com/blog/.

To fix for single language websites hosting assets from CDN, this you may override fastsearch.js#L35 and placing appropriate URL as in

xhr.open("GET", "https://example.com/index.json");

Posts from only one folder/section visible on home page

That is because PaperMod uses mainsections from Hugo. Read more: https://gohugo.io/functions/where/#mainsections

If you have not set this config parameter in site config, it will default to the section with the most pages. You can customize it with:

params:
  mainSections:
  - blog
  - docs

References

Override a Hugo theme

Go-To-Top 🔝

ToC