Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pranavarya37/hugo-papermod-config
This repository provides a deep dive into the hugo.yaml configuration file for the PaperMod Hugo theme, making it easy to customize your website's look, feel, and features.
https://github.com/pranavarya37/hugo-papermod-config
Last synced: 3 days ago
JSON representation
This repository provides a deep dive into the hugo.yaml configuration file for the PaperMod Hugo theme, making it easy to customize your website's look, feel, and features.
- Host: GitHub
- URL: https://github.com/pranavarya37/hugo-papermod-config
- Owner: PranavArya37
- Created: 2024-06-21T23:23:04.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2024-06-21T23:25:00.000Z (5 months ago)
- Last Synced: 2024-06-22T14:18:15.467Z (5 months ago)
- Size: 5.86 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
## How to Configure PaperMod with `hugo.yaml`: A Step-by-Step Tutorial
This guide thoroughly examines a `hugo.yaml` configuration file designed for the elegant and versatile [PaperMod](https://github.com/adityatelange/hugo-PaperMod) theme. We'll break down every setting with clear explanations, illustrative examples, and helpful visuals, empowering you to tailor your Hugo website precisely to your needs.
**Ready to unlock the power of `hugo.yaml`? Let's get started!**
### 1. Basic Site Configuration
```yaml
baseURL: "https://example.com/" # Update with your site's URL (No default - REQUIRED)
title: "My Awesome Website" # Update with your site title (No default)
copyright: "© 2023 Your Website Name. All rights reserved." (No default)
paginate: 5 # (Default: -1, which shows all content on a single page)
theme: ["PaperMod"] # (No default - You must specify a theme)
```
* **`baseURL`:** The foundation for all your website's URLs, **crucial for deployment!**
* **Example:**
* `"https://yourdomain.com/"`
* `"https://yourusername.github.io/your-repo-name/"`
* **Importance:** Hugo uses `baseURL` to build all internal links. An incorrect value will lead to broken links on your deployed site. **This value is REQUIRED and has no default.**
* **`title`:** Your website's name, displayed in browser tabs and used for SEO.
* **Example:** `"My Portfolio"`, `"Coding Adventures"`, `"The Art of Web Design"`
* **This value has no default and should be set to something meaningful for your site.**
* **`copyright`:** Your copyright notice, commonly displayed in the footer.
* **Example:** `"© 2023 Your Website Name. All rights reserved."`
* **This value has no default.**
* **`paginate`:** Controls the maximum number of content items (like blog posts) to show per page in list views.
* **Example:** `paginate: 5` limits each list page to 5 items. If you have 12 blog posts, they'll be spread across 3 pages.
* **Default:** `-1` (shows all content on one page).
* **`theme`:** Specifies the visual theme and layout of your website.
* **Example:** `theme: ["PaperMod"]` activates the [PaperMod](https://github.com/adityatelange/hugo-PaperMod) theme, known for its elegance and customization options.
* **You must specify a theme; there is no default.**
**Visual Example (`paginate`)**
Imagine you have 10 blog posts:
* **`paginate: 5`:**
* Page 1: Posts 1-5
* Page 2: Posts 6-10
* **`paginate: 10`:**
* Page 1: All 10 posts
### 2. Content Building and Processing
```yaml
enableInlineShortcodes: true # (Default: true)
enableRobotsTXT: true # (Default: false)
buildDrafts: false # (Default: false)
buildFuture: false # (Default: false)
buildExpired: false # (Default: false)
enableEmoji: true # (Default: false)
pygmentsUseClasses: true # (Default: true)
mainsections: ["posts", "papermod"] # (Default: none - depends on your content structure)
```
* **`enableInlineShortcodes`:** Enables the use of Hugo's convenient shortcodes directly within your content files.
* **Example:** `{{< figure src="/images/my-image.jpg" alt="A beautiful landscape" >}}` embeds an image with alt text.
* **Benefit:** Enhances content readability and organization.
* **`enableRobotsTXT`:** Automatically generates a `robots.txt` file, crucial for SEO.
* **Effect:** Instructs search engine crawlers on which parts of your site to index.
* **`buildDrafts`, `buildFuture`, `buildExpired`:** Control how Hugo handles content marked as drafts, scheduled for the future, or set to expire.
* **Use Cases:**
* `buildDrafts: false` hides draft content from your live site.
* `buildFuture: true` publishes content scheduled for future dates.
* **`enableEmoji`:** Enables direct emoji support in your content. 🎉
* **Example:** Freely use emojis like 👍 and 🚀 in your Markdown files.
* **`pygmentsUseClasses`:** Employs CSS classes instead of inline styles for syntax highlighting in code blocks, promoting clean HTML.
* **Benefit:** Makes it easier to customize code styles with your own CSS.
* **`mainsections`:** Defines the primary sections of your website's content.
* **Example:** `mainsections: ["blog", "projects"]`
* **Theme Usage:** Themes can use this information for navigation, content organization, or special display features. This value is dependent on how you structure your content and does not have a universal default.
### 3. Minification (`minify`)
```yaml
# minify:
# disableXML: true # (Default: false)
# # minifyOutput: true # (Default: false)
```
* **Minification:** The process of reducing file sizes to improve website loading speed. This benefits both SEO and user experience.
* **`disableXML`:** Disables XML minification, useful if your site doesn't use XML files.
* **`minifyOutput`:** Minifies the final HTML output of your website, further reducing file sizes.
**Note:** These settings are commented out (`#`) in the example, indicating they are inactive by default. To enable them, simply remove the `#`.
**Example (HTML Minification):**
```html
This is some text on my website.
This is some text on my website.
```
### 4. Multilingual Websites (`languages`)
```yaml
# languages:
# en:
# languageName: "English"
# weight: 1
# taxonomies:
# category: categories
# tag: tags
# series: series
# menu:
# main:
# - name: Archive
# url: archives
# weight: 5
# - name: Search
# url: search/
# weight: 10
# - name: Tags
# url: tags/
# weight: 10
# - name: Wiki
# url: https://github.com/adityatelange/hugo-PaperMod/wiki/
# # ... (Settings for other languages)
```
This section configures support for multiple languages. It is currently commented out (`#`), indicating a single-language website. To enable multilingual support, uncomment the `languages` section and add configurations for each supported language:
* **`languageName`:** The human-readable name of the language.
* **Example:** `languageName: "English"`
* **`weight`:** Determines the order in which languages are displayed (important for language switchers). Lower weight values take precedence.
* **Example:**
```yaml
en:
weight: 1
fr:
weight: 2
```
This configuration makes English the default language.
* **`taxonomies`:** Configures categories, tags, or series specifically for each language.
* **Example:**
```yaml
en:
taxonomies:
category: categories
tag: tags
series: series
```
* **`menu`:** Defines the structure of the navigation menu for each language.
* **Example:**
```yaml
en:
menu:
main:
- name: Archive
url: archives
weight: 5
- name: Search
url: search/
weight: 10
# ... (Add more menu items)
```
* **`params`:** (See the following section for language-specific parameters).
### 5. Global and Theme-Specific Parameters (`params`)
```yaml
params:
env: production # (No default - but often set to "development" or "production")
description: "A beautiful and fast Hugo theme." # (No default)
author: "Theme Author" # (No default)
defaultTheme: auto # (Default: "auto")
disableThemeToggle: true # (Default: false)
ShowShareButtons: true # (Default: false)
ShowReadingTime: true # (Default: false)
disableSpecial1stPost: true # (Default: false)
displayFullLangName: true # (Default: false)
ShowPostNavLinks: true # (Default: true)
ShowBreadCrumbs: true # (Default: true)
ShowCodeCopyButtons: true # (Default: false)
ShowRssButtonInSectionTermList: true # (Default: false)
ShowAllPagesInArchive: true # (Default: false)
ShowPageNums: true # (Default: true)
ShowToc: true # (Default: true)
comments: false # (Default: false - requires additional commenting system setup)
images: ["images/placeholder-image.jpg"] # (Default: none)
profileMode:
enabled: false # (Default: false)
title: "My Portfolio" # (No default)
imageUrl: "#" # (No default)
imageTitle: "My Profile Image" # (No default)
# imageWidth: 120
# imageHeight: 120
buttons:
- name: Archives
url: archives
- name: Tags
url: tags
homeInfoParams:
Title: "Welcome to My Website" # (No default)
Content: >
This is a sample website built with Hugo and the PaperMod theme. # (No default)
socialIcons:
- name: github
title: View Source on GitHub
url: "https://github.com/example/your-repo"
# ... (You can add more social media icons here)
editPost:
URL: "https://github.com/example/your-repo/edit/main/content" # (No default)
Text: "Suggest Changes" # (Default: "Edit")
appendFilePath: true # (Default: false)
```
The `params` section serves as a central repository for global data that you can use throughout your Hugo website:
* **`env`:** Often used to set the environment (e.g., "development" or "production"), which can influence other configurations.
* **Example:** Use different analytics tracking codes based on the environment.
* **This value has no default but is commonly set to either "development" or "production."**
* **`description`:** A concise and informative summary of your website. This is important for SEO.
* **Example:** `"A blog dedicated to exploring the latest trends in web development."`
* **This value has no default.**
* **`author`:** Your name or the name of the website's author.
* **This value has no default.**
**General Parameters:**
* **`defaultTheme`**: Controls the default website theme (light/dark mode).
* **Options:** `"auto"`, `"light"`, `"dark"`
* **Default:** `"auto"` (usually respects user's system preference)
* **`disableThemeToggle`:** Disables the theme switcher if set to `true`.
* **`ShowShareButtons`, `ShowReadingTime`, `disableSpecial1stPost`**: Configure the display of social sharing buttons, estimated reading times for articles, and whether to visually distinguish the first post on a page.
* **`displayFullLangName`**: If you have a multilingual site, this controls whether to show the full language name (e.g., "English") or a shorter representation (e.g., "en").
* **`ShowPostNavLinks`, `ShowBreadCrumbs`**: Manage the display of navigation links between posts and breadcrumbs (navigation aids).
* **`ShowCodeCopyButtons`, `ShowRssButtonInSectionTermList`, `ShowAllPagesInArchive`, `ShowPageNums`, `ShowToc`**: Fine-tune content browsing options, including:
* Showing code copy buttons for code blocks
* RSS feed links in section term lists
* Archive page settings
* Page numbers
* Table of contents (TOC)
* **`comments`**: Enables or disables comments. Usually requires additional setup with a commenting system.
* **`images`**: An array of image paths to be used as cover images across your website.
**PaperMod Theme-Specific Parameters:**
* **`profileMode`**: Activate and customize "profile mode" to showcase your work in a portfolio or resume-style format.
* **`enabled`:** Set to `true` to activate.
* **`title`, `imageUrl`, `imageTitle`, `imageWidth`, `imageHeight`**: Configure the look of your profile image and title.
* **`buttons`**: Add buttons to link to portfolio sections.
* **`homeInfoParams`**: Customize the content shown on your homepage.
* **`Title`**: The main heading.
* **`Content`**: The main content (supports Markdown).
* **`socialIcons`**: Define links to your social media profiles. PaperMod styles and displays these.
* **`name`**: The social media platform (e.g., "github", "twitter").
* **`title`**: Tooltip text on hover.
* **`url`**: Your profile's URL.
* **`editPost`**: Include links to your content files for streamlined editing. This is commonly used for sites with content stored in Git repositories.
* **`URL`**: The base URL of your content repository.
* **`Text`**: The visible text of the edit link.
* **`appendFilePath`**: Determines whether to append the full file path to the edit link.
### 6. Assets, Markdown Processing, and External Services
```yaml
assets:
disableHLJS: true # (Default: false)
# favicon: "" # (No default - specify favicon paths)
# favicon16x16: ""
# favicon32x32: ""
# apple_touch_icon: ""
# safari_pinned_tab: ""
# markup:
# goldmark:
# renderer:
# unsafe: true # (Default: false - use with extreme caution)
# highlight:
# noClasses: false # (Default: false)
# services:
# instagram:
# disableInlineCSS: true # (Default: false)
# twitter:
# disableInlineCSS: true # (Default: false)
```
* **`assets`**: Manages how Hugo handles your website's static assets (images, CSS, and JavaScript files).
* **`disableHLJS`**: Disables the Highlight.js library for syntax highlighting if you're using a different solution.
* **Favicons**: The commented-out `favicon` options let you specify paths to different icon files for various devices and contexts, important for branding and a consistent look. You'll need to uncomment and provide the paths to your favicon files.
* **`markup`**: Configures how Hugo processes Markdown content and handles syntax highlighting.
* **`goldmark`**: Settings for the Goldmark Markdown parser.
* **`renderer.unsafe`: `true`** enables the use of raw HTML within your Markdown content. **Use with EXTREME CAUTION, as it can introduce security vulnerabilities.**
* **`highlight`**: Customizes syntax highlighting using the Chroma highlighter.
* **`noClasses`**: Defaults to `false`. When set to `false`, it applies CSS classes for styling code blocks, making it easy to customize their appearance using your CSS.
* **`services`**: Integrates with external services, often for embedding content like social media posts.
* **`instagram`, `twitter`**: Configurations for embedding content from these platforms.
* **`disableInlineCSS`**: Setting this to `true` typically removes inline CSS styles from embedded content, giving you more control over their appearance using your website's CSS.
---
### Conclusion
You've now completed an in-depth exploration of this PaperMod-ready `hugo.yaml` configuration. Remember these essential tips:
* **Context Matters:** Many settings are theme-specific. Consult your theme's documentation for complete explanations.
* **Experiment Boldly:** Don't be afraid to adjust settings and observe their impact on your site. This hands-on experience is invaluable.
* **Embrace Resources:** The official [Hugo documentation](https://gohugo.io/documentation/) and the [PaperMod GitHub repository](https://github.com/adityatelange/hugo-PaperMod) are excellent resources for advanced learning and customization.
**Happy website building!** 🚀
## PaperMod `hugo.yaml` Configuration Guide: Explained with Examples