From f80812cb389f85afa04afab13d217842b80e562f Mon Sep 17 00:00:00 2001 From: Igor Baiborodine Date: Wed, 1 Jun 2022 08:35:39 -0400 Subject: Idea/use theme as Hugo module (#400) Use theme as Hugo module --- .github/workflows/update-demo-page.yml | 10 ++-- README.md | 94 +++++++++++++++++++++++----------- exampleSite/config.toml | 7 ++- exampleSite/go.mod | 3 -- 4 files changed, 77 insertions(+), 37 deletions(-) delete mode 100644 exampleSite/go.mod diff --git a/.github/workflows/update-demo-page.yml b/.github/workflows/update-demo-page.yml index dcc1f88..77d056e 100644 --- a/.github/workflows/update-demo-page.yml +++ b/.github/workflows/update-demo-page.yml @@ -42,15 +42,17 @@ jobs: - name: Adjust the baseURL for gh-pages run: sed -i "s/baseURL = .*$/baseURL = \"https:\/\/lednerb.github.io\/bilberry-hugo-theme\/\"/" /tmp/demo-site/config.toml - - name: Copy theme to the right location - run: mkdir /tmp/demo-site/themes/bilberry-hugo-theme && cp -r * /tmp/demo-site/themes/bilberry-hugo-theme + - name: Init Hugo module + working-directory: /tmp/demo-site + run: hugo mod init github.com/Lednerb/bilberry-hugo-theme/exampleSite - name: Build - run: cd /tmp/demo-site && hugo && > public/.nojekyll + working-directory: /tmp/demo-site + run: hugo && > public/.nojekyll - name: Deploy to GitHub Pages if: success() - uses: crazy-max/ghaction-github-pages@v2 + uses: crazy-max/ghaction-github-pages@v3 with: target_branch: gh-pages build_dir: ../../../../../../../../tmp/demo-site/public diff --git a/README.md b/README.md index b083392..5757323 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,13 @@ Please use the following guidelines if you want to start a discussion: - [Requirements](#requirements) - [Quick Start](#quick-start) -- [Configuration](#configuration) + - [Site Initial Setup](#site-initial-setup) + - [Theme Installation Options](#theme-installation-options) + - [Option 1 (recommended): Adding the Theme as a Hugo Module](#option-1-recommended-adding-the-theme-as-a-hugo-module) + - [Option 2: Cloning/Copying the Theme Files](#option-2-cloningcopying-the-theme-files) + - [Configuration](#configuration) + - [Webserver](#webserver) + - [Other Tutorials](#other-tutorials) - [Features](#features) - [Post Types](#post-types) - [Top Navigation Bar](#top-navigation-bar) @@ -75,56 +81,86 @@ Please use the following guidelines if you want to start a discussion: - [License](#license) ## Requirements - -**Hugo version >= 0.83.0 required**; see this [guide](https://gohugo.io/getting-started/installing/) on how to install Hugo. -Only when using theme as Hugo module: -**Git optional**; download Git installer [here](https://git-scm.com/downloads) +- **Hugo** (version >= 0.83.0), see this [guide](https://gohugo.io/getting-started/installing/) on how to install Hugo. +- **Git**, see this [guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) on how to install Git. +- **Go** (version >= 1.18), optional, required only when the Bilberry theme is used as a Hugo module; see this [guide](https://go.dev/doc/install) on how to install Go. ## Quick Start -- Create a new site: +### Site Initial Setup +- Clone the Bilberry Hugo theme repository to your local computer: +```shell +git clone https://github.com/Lednerb/bilberry-hugo-theme.git ``` +Alternatively, you can download it as a [ZIP](https://github.com/Lednerb/bilberry-hugo-theme/archive/master.zip) file and extract into the `bilberry-hugo-theme` directory. + +- Create a new site: +```shell hugo new site my-new-blog ``` -- Install the latest version of this theme: -``` -cd my-new-blog/themes -git clone https://github.com/Lednerb/bilberry-hugo-theme.git +- Delete the default archetype: +```shell +rm my-new-blog/archetypes/default.md ``` -If you don't use **Git**, you can download this theme [here](https://github.com/Lednerb/bilberry-hugo-theme/archive/master.zip) and extract it manually into the `themes` folder. -Make sure the folder containing the extracted theme is named `bilberry-hugo-theme`. -- Copy example site content including the `config.toml` file: -``` -cp -r bilberry-hugo-theme/exampleSite/* ../ +- Copy the example site content including the `config.toml` file: +```shell +cp -r bilberry-hugo-theme/exampleSite/* my-new-blog ``` -- Remove the default archetype: -``` -cd ../ -rm archetypes/default.md -``` -- Configure the necessary properties in the `config.toml` file. Then start the webserver and to publish your website: +### Theme Installation Options +#### Option 1 (recommended): Adding the Theme as a Hugo Module +Use this option if you want to pull in the theme files from the main Bilberry Hugo theme repository. +This option makes it easy to keep the theme up to date in your site. + +- Initialize your website as a Hugo module from the site's root: +```shell +cd my-new-blog +hugo mod init github.com//my-new-blog ``` -hugo server +Following the Hugo module initialization, you may have the following warning: module "github.com/Lednerb/bilberry-hugo-theme/v3" not found, which should be ignored. + +If you need more details on how to use Hugo modules, please read the [Hugo documentation](https://gohugo.io/hugo-modules/use-modules/). + +#### Option 2: Cloning/Copying the Theme Files +Use this option if you want to directly customize and maintain your own copy of the theme. + +- In the `my-new-blog/config.toml` file, uncomment the `theme` property for **Option 2**, and comment out the `theme` property for **Option 1**: +```toml +# Option 1 (recommended): adding the theme as a hugo module +# theme = "github.com/Lednerb/bilberry-hugo-theme/v3" + +# Option 2: cloning/copying the theme files +theme = "bilberry-hugo-theme" ``` -**Important:** Do NOT change the name of the `bilberry-hugo-theme` folder. +- Copy cloned (or unzipped) theme files in previous step to the `my-new-blog/themes` directory: +```shell +cp -r bilberry-hugo-theme my-new-blog/themes/bilberry-hugo-theme +``` +**Important:** Do NOT change the name of the `themes/bilberry-hugo-theme` folder in your site's root. Renaming this folder will break your site. -Also, check out this [tutorial](https://www.kiroule.com/article/start-blogging-with-github-hugo-and-netlify/) on how to build a Bilberry theme-based website using Hugo, GitHub, and Netlify. - -## Configuration -To customize your site according to your needs, edit the `config.toml` file in the site's root directory by adjusting the settings. +### Configuration +To customize website according to your needs, edit the `config.toml` file in the site's root directory by adjusting the settings. All parameters that need to be configured are commented out or disabled. The Algolia Search is enabled in the `config.toml` file that comes with the example site; therefore, if you don't plan to use it, disable it by setting the `algolia_search` property to `false`. -Also, you can read this [write-up](https://www.kiroule.com/article/manage-environment-specific-settings-for-hugo-based-website/) on how to manage -environment-specific settings for a Hugo-based website. +### Webserver +- To build and serve the site, execute the following command from the site's root: +```shell +cd my-new-blog +hugo server +``` + +### Other Tutorials +- [Start Blogging With Hugo, GitHub, and Netlify](https://www.kiroule.com/article/start-blogging-with-github-hugo-and-netlify/) +- [Configure Custom Domain and HTTPS on Netlify](https://www.kiroule.com/article/configure-custom-domain-and-https-in-netlify/) +- [Manage Environment-Specific Settings for Hugo-Based Website](https://www.kiroule.com/article/manage-environment-specific-settings-for-hugo-based-website/) ## Features diff --git a/exampleSite/config.toml b/exampleSite/config.toml index 44d2b88..b7c835f 100644 --- a/exampleSite/config.toml +++ b/exampleSite/config.toml @@ -1,6 +1,11 @@ title = "My cool new Blog" baseURL = "https://example.com/" -theme = "bilberry-hugo-theme" + +# Option 1 (recommended): adding the theme as a Hugo module +theme = "github.com/Lednerb/bilberry-hugo-theme/v3" + +# Option 2: cloning/copying the theme files +# theme = "bilberry-hugo-theme" # Generate the robots.txt file for SEO enableRobotsTXT = true diff --git a/exampleSite/go.mod b/exampleSite/go.mod deleted file mode 100644 index 69e659e..0000000 --- a/exampleSite/go.mod +++ /dev/null @@ -1,3 +0,0 @@ -module github.com/Lednerb/bilberry-hugo-theme/exampleSite - -go 1.18 -- cgit v1.2.3