--- title: "FAQs" summary: Frequently Asked Questions date: 2021-01-20 aliases: ["/papermod-how-to-guide"] tags: ["PaperMod"] author: "Aditya Telange" draft: true aliases: [/posts/papermod/papermod-how-to] weight: 3 --- ## 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](https://www.google.com/search?q=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: ```shell your-site/themes/papermod/layouts/_defaults/list.html ``` And paste it under your own `layouts` folder: ```shell 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`. --- ## Enable Social-Metadata and SEO These include OpenGraph, Twitter Cards and Schema. ```yml 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](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) Why was the `asset` not loading ? : [How_browsers_handle_Subresource_Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity#How_browsers_handle_Subresource_Integrity) **Solution:** Set the following in `config.yml` ```yml params: assets: disableFingerprinting: true ``` Linked Issues: - https://stackoverflow.com/questions/65056585/hugo-theme-not-loading - https://stackoverflow.com/questions/65040931/hugo-failed-to-find-a-valid-digest-in-the-integrity-attribute-for-resource - https://blog.gerardbeckerleg.com/posts/hugo-failed-to-find-a-valid-digest-in-the-integrity-attribute-for-resource/ --- ## 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?](https://discourse.gohugo.io/t/papermod-theme-how-to-add-custom-css/30165) --- ## 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. --- ## Add menu to site 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`: ```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](https://gohugo.io/content-management/menus/). --- ## Pin a Post Post can be pinned/ displayed top on the list by adding a `weight=` var to page-variables example: ```yml --- title: "My Important post" date: 2020-09-15T11:30:03+00:00 weight: 1 --- ``` ```yml --- 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` 1. Favicon(s) can be generated by [Favicon.io](https://favicon.io) and can be simply put in `/static` folder. 2. Other way is to add favicon(s) NOT located in `/static` folder. In site config add the following: ``` params: assets: favicon: "" favicon16x16: "" favicon32x32: "" apple_touch_icon: "" safari_pinned_tab: "" ``` - `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 ```md ![name](path/to/image.png#center) ``` **When using [`figure`](https://gohugo.io/content-management/shortcodes/) shortcode** use `align=center` to center image with captions ex. ```md {{}} ``` --- ## Using Hugo's Syntax highlighter "chroma" 1. Disable Highlight.js in site `config.yml` ```yml params: assets: disableHLJS: true ``` 2. Set hugo's markdown styling in site `config.yml` ```yml markup: highlight: # anchorLineNos: true codeFences: true guessSyntax: true lineNos: true # noClasses: false style: monokai ``` 3. 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](https://gohugo.io/content-management/syntax-highlighting/#generate-syntax-highlighter-css) Add the following to `assets/css/extended/custom.css` ```css .chroma { background-color: unset; } ``` More Info : [Configure Markup - Highlight](https://gohugo.io/getting-started/configuration-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](https://github.com/adityatelange/hugo-PaperMod/blob/fb4988cfb6d0d6e4e489f17d89f0fa618def3396/assets/js/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](#override-theme-template) [fastsearch.js#L35](https://github.com/adityatelange/hugo-PaperMod/blob/fb4988cfb6d0d6e4e489f17d89f0fa618def3396/assets/js/fastsearch.js#L35) and placing appropriate URL as in ```js xhr.open("GET", "https://example.com/index.json"); ``` --- ## References - [Override a Hugo theme](https://zwbetz.com/override-a-hugo-theme/)