hugo-PaperMod/content/posts/papermod/papermod-installation.md

373 lines
10 KiB
Markdown
Raw Normal View History

2020-09-17 10:58:09 +02:00
---
2023-12-15 17:22:06 +01:00
title: "Install / Update PaperMod"
summary: Read aboout Install and Update instructions and sampled configuration templates
date: 2021-01-20
2020-09-17 10:58:09 +02:00
series: ["PaperMod"]
weight: 1
2020-10-27 14:16:08 +01:00
aliases: ["/papermod-installation"]
2023-12-15 17:22:06 +01:00
tags: ["PaperMod", "Docs"]
author: ["Aditya Telange"]
cover:
image: images/papermod-cover.png
hiddenInList: true
2020-09-17 10:58:09 +02:00
---
2023-12-17 10:13:23 +01:00
> - **We'll be using `yml/yaml` format for all examples down below, it is recommend to use `yaml` 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 needed.
2021-02-07 17:25:52 +01:00
---
2021-03-31 08:10:14 +02:00
2023-12-17 10:13:23 +01:00
## Getting Started 🚀
1. Follow **[Hugo Docs's - Quick Start](https://gohugo.io/getting-started/quick-start/)** guide to install {{< inTextImg url="https://raw.githubusercontent.com/gohugoio/hugoDocs/master/static/img/hugo-logo.png" height="14" >}}.
<br>(Make sure you install **Hugo >= v0.112.4**)
2020-10-06 09:31:20 +02:00
2023-12-17 10:13:23 +01:00
2. Create a new {{< inTextImg url="https://raw.githubusercontent.com/gohugoio/hugoDocs/master/static/img/hugo-logo.png" height="14" >}} site
```sh
hugo new site MyFreshWebsite --format yaml
# replace MyFreshWebsite with name of your website
```
Note:
- Older versions of Hugo may not support `--format yaml`
- Read more here about [Hugo Docs's - hugo new site command](https://gohugo.io/commands/hugo_new_site/#synopsis)
2021-02-07 17:25:52 +01:00
2023-12-17 10:13:23 +01:00
After you have created a new site, follow the below steps to add **PaperMod**
2021-02-07 17:25:52 +01:00
2023-12-17 10:13:23 +01:00
### Installing/Updating PaperMod
2020-09-17 10:58:09 +02:00
2023-12-17 10:13:23 +01:00
- Themes reside in `MyFreshWebsite/themes` directory.
- PaperMod will be installed in `MyFreshWebsite/themes/PaperMod`
2020-09-17 10:58:09 +02:00
2023-12-17 10:13:23 +01:00
> {{< collapse summary="**Expand Method 1 - Git Clone**" >}}
2023-12-17 10:13:23 +01:00
**INSTALL** : Inside the folder of your Hugo site `MyFreshWebsite`, run:
2020-09-17 10:58:09 +02:00
```bash
git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1
```
2023-12-17 10:13:23 +01:00
You may use ` --branch v7.0` to end of above command if you want to stick to specific release.
**UPDATE**: Inside the folder of your Hugo site `MyFreshWebsite`, run:
```bash
cd themes/PaperMod
git pull
```
2023-12-17 10:13:23 +01:00
{{</ collapse >}}
2023-12-17 10:13:23 +01:00
> {{< collapse summary="**Expand Method 2 - Git Submodule (recomended)**" >}}
2023-12-17 10:13:23 +01:00
**INSTALL** : Inside the folder of your Hugo site `MyFreshWebsite`, run:
```bash
2022-06-10 18:19:13 +02:00
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
2021-02-07 17:25:52 +01:00
git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)
```
2023-12-17 10:13:23 +01:00
You may use ` --branch v7.0` to end of above command if you want to stick to specific release.
Read more about git submodules [here](https://www.atlassian.com/git/tutorials/git-submodule).
**UPDATE**: Inside the folder of your Hugo site `MyFreshWebsite`, run:
```bash
git submodule update --remote --merge
```
2023-12-17 10:13:23 +01:00
{{</ collapse >}}
2023-12-17 10:13:23 +01:00
> {{< collapse summary="**Expand Method 3 - Download an unzip**" >}}
2023-12-17 10:13:23 +01:00
Download PaperMod source as Zip from Github Releases and extract in your themes directory at `MyFreshWebsite/themes/PaperMod`
2021-02-01 06:47:12 +01:00
Direct Links:
2022-06-10 18:19:13 +02:00
- [Master Branch (Latest)](https://github.com/adityatelange/hugo-PaperMod/archive/master.zip)
2023-12-17 10:13:23 +01:00
- [v7.0](https://github.com/adityatelange/hugo-PaperMod/archive/v7.0.zip)
2022-06-10 18:19:13 +02:00
- [v6.0](https://github.com/adityatelange/hugo-PaperMod/archive/v6.0.zip)
- [v5.0](https://github.com/adityatelange/hugo-PaperMod/archive/v5.0.zip)
- [v4.0](https://github.com/adityatelange/hugo-PaperMod/archive/v4.0.zip)
- [v3.0](https://github.com/adityatelange/hugo-PaperMod/archive/v3.0.zip)
- [v2.0](https://github.com/adityatelange/hugo-PaperMod/archive/v2.0.zip)
- [v1.0](https://github.com/adityatelange/hugo-PaperMod/archive/v1.0.zip)
2021-02-01 06:47:12 +01:00
2023-12-17 10:13:23 +01:00
{{</ collapse >}}
> {{< collapse summary="**Expand Method 4 - Hugo module**" >}}
**INSTALL** :
2023-12-15 17:22:06 +01:00
- Install [Go programming language](https://go.dev/doc/install) in your operating system.
- Intialize your own hugo mod
```
hugo mod init YOUR_OWN_GIT_REPOSITORY
```
2023-12-15 17:22:06 +01:00
- Add PaperMod in your `config.yml` file
2023-12-15 17:22:06 +01:00
```go {linenos=true}
module:
imports:
- path: github.com/adityatelange/hugo-PaperMod
```
2023-12-15 17:22:06 +01:00
2023-12-17 10:13:23 +01:00
**UPDATE**:
```
hugo mod get -u
```
2020-09-17 10:58:09 +02:00
2023-12-17 10:13:23 +01:00
Read more : [Hugo Docs's - HUGO MODULES](https://gohugo.io/hugo-modules/use-modules/)
{{</ collapse >}}
2022-12-18 18:22:07 +01:00
2023-12-17 10:13:23 +01:00
### Finally set theme as PaperMod in your site config
In `config.yml` add:
2022-12-18 18:22:07 +01:00
2023-12-15 17:22:06 +01:00
```yml {linenos=true}
2023-12-17 10:13:23 +01:00
theme: ["PaperMod"]
2022-12-18 18:22:07 +01:00
```
2023-12-17 10:13:23 +01:00
### Next up - Customizing PaperMod to suit your preferences.
- Your site will be blank after you set up for the very first time.
- You may go through this website's source code - [PaperMod's exampleSite's souce](https://github.com/adityatelange/hugo-PaperMod/tree/exampleSite)
- Scroll below this page where you will find more specific details about each section.
- Kindly go through all of the pages below to know how to configure PaperMod.
---
## Support 🫶
- Star 🌟 PaperMod's Github repository.
- Help spread the word about PaperMod by sharing it on social media and recommending it to your friends. 🗣️
- You can also sponsor 🏅 on [Github Sponsors](https://github.com/sponsors/adityatelange) / [Ko-Fi](https://ko-fi.com/adityatelange).
2022-12-18 18:22:07 +01:00
---
2023-12-15 17:22:06 +01:00
## Videos featuring PaperMod
2022-12-18 18:22:07 +01:00
You can go through few videos which are available on YouTube for getting to know the creator's thoughts as well as the setup process.
▶️ https://youtube.com/playlist?list=PLeiDFxcsdhUrzkK5Jg9IZyiTsIMvXxKZP
---
## Quick Links
2023-12-15 17:22:06 +01:00
- ### [Papermod - Features](../papermod-features)
2023-12-15 17:22:06 +01:00
- ### [Papermod - FAQs](../papermod-how-to)
2023-12-15 17:22:06 +01:00
- ### [Papermod - Variables](../papermod-variables)
2023-12-15 17:22:06 +01:00
- ### [Papermod - Icons](../papermod-icons)
2023-12-15 17:22:06 +01:00
- ### [ChangeLog](https://github.com/adityatelange/hugo-PaperMod/releases)
2020-09-17 10:58:09 +02:00
---
## Sample `config.yml`
> **Example Site Structure is present here**: [exampleSite](https://github.com/adityatelange/hugo-PaperMod/tree/exampleSite/)
**Use appropriately**
2020-10-06 09:31:20 +02:00
```yml
2021-03-31 06:07:24 +02:00
baseURL: "https://examplesite.com/"
2020-10-06 09:31:20 +02:00
title: ExampleSite
paginate: 5
theme: PaperMod
2020-10-06 09:31:20 +02:00
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
2020-11-03 10:45:58 +01:00
buildExpired: false
2020-10-06 09:31:20 +02:00
googleAnalytics: UA-123-45
minify:
2022-06-10 18:19:13 +02:00
disableXML: true
minifyOutput: true
2020-10-06 09:31:20 +02:00
params:
2022-06-10 18:19:13 +02:00
env: production # to enable google analytics, opengraph, twitter-cards and schema.
title: ExampleSite
description: "ExampleSite description"
keywords: [Blog, Portfolio, PaperMod]
author: Me
# author: ["Me", "You"] # multiple authors
images: ["<link or path of image for opengraph, twitter-cards>"]
DateFormat: "January 2, 2006"
defaultTheme: auto # dark, light
disableThemeToggle: false
ShowReadingTime: true
ShowShareButtons: true
ShowPostNavLinks: true
ShowBreadCrumbs: true
ShowCodeCopyButtons: false
ShowWordCount: true
ShowRssButtonInSectionTermList: true
UseHugoToc: true
disableSpecial1stPost: false
disableScrollToTop: false
comments: false
hidemeta: false
hideSummary: false
showtoc: false
tocopen: false
assets:
# disableHLJS: true # to disable highlight.js
# disableFingerprinting: true
favicon: "<link / abs url>"
favicon16x16: "<link / abs url>"
favicon32x32: "<link / abs url>"
apple_touch_icon: "<link / abs url>"
safari_pinned_tab: "<link / abs url>"
label:
text: "Home"
icon: /apple-touch-icon.png
iconHeight: 35
# profile-mode
profileMode:
enabled: false # needs to be explicitly set
2020-10-06 09:31:20 +02:00
title: ExampleSite
2022-06-10 18:19:13 +02:00
subtitle: "This is subtitle"
imageUrl: "<img location>"
imageWidth: 120
imageHeight: 120
imageTitle: my image
buttons:
- name: Posts
url: posts
- name: Tags
url: tags
# home-info mode
homeInfoParams:
Title: "Hi there \U0001F44B"
Content: Welcome to my blog
socialIcons:
- name: twitter
url: "https://twitter.com/"
- name: stackoverflow
url: "https://stackoverflow.com"
- name: github
url: "https://github.com/"
analytics:
google:
SiteVerificationTag: "XYZabc"
bing:
SiteVerificationTag: "XYZabc"
yandex:
SiteVerificationTag: "XYZabc"
cover:
hidden: true # hide everywhere but not in structured data
hiddenInList: true # hide on list pages and home
hiddenInSingle: true # hide on single page
editPost:
URL: "https://github.com/<path_to_repo>/content"
Text: "Suggest Changes" # edit text
appendFilePath: true # to append file path to Edit link
# for search
# https://fusejs.io/api/options.html
fuseOpts:
isCaseSensitive: false
shouldSort: true
location: 0
distance: 1000
threshold: 0.4
minMatchCharLength: 0
limit: 10 # refer: https://www.fusejs.io/api/methods.html#search
2022-06-10 18:19:13 +02:00
keys: ["title", "permalink", "summary", "content"]
2020-12-15 18:41:18 +01:00
menu:
2022-06-10 18:19:13 +02:00
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
# Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma
2022-06-10 18:19:13 +02:00
pygmentsUseClasses: true
markup:
highlight:
noClasses: false
# anchorLineNos: true
# codeFences: true
# guessSyntax: true
# lineNos: true
# style: monokai
2020-10-06 09:31:20 +02:00
```
---
## Sample `Page.md`
2020-10-06 09:31:20 +02:00
```yml
---
title: "My 1st post"
date: 2020-09-15T11:30:03+00:00
# weight: 1
# aliases: ["/first"]
2020-10-27 14:16:08 +01:00
tags: ["first"]
2020-10-06 09:31:20 +02:00
author: "Me"
2020-10-25 08:48:45 +01:00
# author: ["Me", "You"] # multiple authors
2020-10-06 09:31:20 +02:00
showToc: true
TocOpen: false
draft: false
hidemeta: false
comments: false
description: "Desc Text."
2021-05-01 18:30:28 +02:00
canonicalURL: "https://canonical.url/to/page"
disableHLJS: true # to disable highlightjs
2020-10-06 09:31:20 +02:00
disableShare: false
disableHLJS: false
2021-03-31 08:10:14 +02:00
hideSummary: false
2021-02-01 06:47:12 +01:00
searchHidden: true
2021-03-31 08:10:14 +02:00
ShowReadingTime: true
ShowBreadCrumbs: true
ShowPostNavLinks: true
2022-06-10 18:19:13 +02:00
ShowWordCount: true
2022-04-30 04:15:10 +02:00
ShowRssButtonInSectionTermList: true
2022-06-10 18:19:13 +02:00
UseHugoToc: true
2020-10-06 09:31:20 +02:00
cover:
image: "<image path/url>" # image path/url
alt: "<alt text>" # alt text
caption: "<text>" # display caption under cover
relative: false # when using page bundles set this to true
hidden: true # only hide on current single page
2021-03-31 08:10:14 +02:00
editPost:
URL: "https://github.com/<path_to_repo>/content"
Text: "Suggest Changes" # edit text
appendFilePath: true # to append file path to Edit link
---
2020-10-06 09:31:20 +02:00
```
2021-02-01 06:47:12 +01:00
You can use it by creating `archetypes/post.md`
```shell
hugo new --kind post <name>
```
2020-10-06 09:31:20 +02:00
---