From a73ca4e7ad85369f4c8581429804b3c7ba6c7cec Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Tue, 17 May 2022 14:36:08 -0700 Subject: [PATCH 1/7] set a minimum version Signed-off-by: Ivan Boothe --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index d02d173d..d4d2ae67 100644 --- a/README.md +++ b/README.md @@ -104,11 +104,13 @@ A technology-minded theme for Hugo based on VMware's open-source [Clarity Design ## Prerequisites -Firstly, __ensure you have installed the [extended version of Hugo](https://github.com/gohugoio/hugo/releases)__. See installation steps from [Hugo's official docs](https://gohugo.io/getting-started/installing/). +Firstly, __ensure you have installed the [extended version of Hugo 0.91.0 or above](https://github.com/gohugoio/hugo/releases)__. See installation steps from [Hugo's official docs](https://gohugo.io/getting-started/installing/) for more information. Note that software repositories may be several versions behind and may not include the extended version. ## Getting up and running -Read the [prerequisites](#prerequisites) above and verify you're using the extended version of Hugo. There are at least two ways of quickly getting started with Hugo and the VMware Clarity theme: +Read the [prerequisites](#prerequisites) above and verify you're using the __extended version of Hugo 0.91.0 or newer__. + +There are at least two ways of quickly getting started with Hugo and the VMware Clarity theme: ### Option 1 (recommended) From 6d4d0195b904a1a4f71167772890d2995b21d5f3 Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Tue, 17 May 2022 14:52:24 -0700 Subject: [PATCH 2/7] adding Gitpod init Signed-off-by: Ivan Boothe --- .gitpod.yml | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .gitpod.yml diff --git a/.gitpod.yml b/.gitpod.yml new file mode 100644 index 00000000..aada5817 --- /dev/null +++ b/.gitpod.yml @@ -0,0 +1,9 @@ +# Hugo template via https://github.com/gitpod-io/template-hugo/blob/main/.gitpod.yml +tasks: + - name: Install and start hugo + before: brew install hugo + init: echo "Your version of Hugo is `hugo version`" + command: cd exampleSite && hugo server -D -F --baseUrl $(gp url 1313) --liveReloadPort=443 --appendPort=false --bind=0.0.0.0 --themesDir ../.. +ports: + - port: 1313 + onOpen: open-preview From 00310017b1c5c1308f9b1045847b23af091c044f Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Tue, 17 May 2022 15:59:15 -0700 Subject: [PATCH 3/7] rework setup/installation section Signed-off-by: Ivan Boothe --- README.md | 80 +++++++++++++++++++++++++++++++------------------------ 1 file changed, 45 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d4d2ae67..576ca698 100644 --- a/README.md +++ b/README.md @@ -110,31 +110,19 @@ Firstly, __ensure you have installed the [extended version of Hugo 0.91.0 or abo Read the [prerequisites](#prerequisites) above and verify you're using the __extended version of Hugo 0.91.0 or newer__. -There are at least two ways of quickly getting started with Hugo and the VMware Clarity theme: +There are several ways to use this theme: -### Option 1 (recommended) +### Option 1a: Development in the browser -Generate a new Hugo site and add this theme as a Git submodule inside your themes folder: +[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/chipzoller/hugo-clarity) -```bash -hugo new site yourSiteName -cd yourSiteName -git init -git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity -cp -a themes/hugo-clarity/exampleSite/* . -``` - -Then run - -```bash -hugo server -``` +For trying out the theme, quick experimentation, and to contribute Pull Requests, Gitpod is the easiest option. Use the button above and it will spin up a prebuilt environment with a site ready to go. -Hurray! +If you want to contribute a PR, [this is a good overview of that process](https://jldec.me/using-gitpod-to-create-a-pr), and there's also an [optional browser extension](https://www.gitpod.io/docs/browser-extension). -### Option 2 (Great for testing quickly) +### Option 1b: Development on your machine -You can run your site directly from the `exampleSite`. To do so, use the following commands: +If you prefer not to use Gitpod, you can also test, develop and contribute PRs locally from your computer. ```bash git clone https://github.com/chipzoller/hugo-clarity @@ -142,37 +130,59 @@ cd hugo-clarity/exampleSite/ hugo server --themesDir ../.. ``` -> Although, option 2 is great for quick testing, it is somewhat problematic when you want to update your theme. You would need to be careful not to overwrite your changes. +> Note that while this is a good way to work on Hugo Clarity, isn't a good way to work on your own site, since it uses the content from `exampleSite`, and wouldn't be aware of any overrides your site might apply to the theme. -### Option 3 (The new, most fun & painless approach) +### Option 2: Hugo modules -This option enables you to load this theme as a hugo module. It arguably requires the least effort to run and maintain your website. +This option arguably requires the least effort to run and maintain your website with the Hugo Clarity theme. -Ensure you have `go` binary [installed on your machine](https://golang.org/doc/install) Note: Mac users: ```brew install go```. +We assume you've already run `hugo new site ` and are in the `` directory. +1. Ensure you have the `go` binary [installed on your machine](https://golang.org/doc/install) Note: Mac users: ```brew install go```. +2. Run the following command, substituting `` with your site's name: +```bash +hugo mod init +``` +3. Hugo Clarity comes with [`exampleSite` files](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite) prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing: +```bash +wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz && cp -a hugo-clarity-master/exampleSite/* . && rm -rf hugo-clarity-master && rm -f config.toml +``` +If you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of [`config`](exampleSite/config/) over, as well as replacing your `archetypes/post.md` (if it exists) with [Hugo Clarity's](exampleSite/archetypes/post.md). Then migrate any necessary settings from `/config.toml` to `/config/_default/config.toml` and remove the original `/config.toml` file. +4. Open `/config/_default/config.toml` and change `theme = "hugo-clarity"` to `theme = ["github.com/chipzoller/hugo-clarity"]` +5. You can now run: ```bash -git clone https://github.com/chipzoller/hugo-clarity.git clarity -cd clarity/exampleSite/ -hugo mod init my-site -cd .. -cp -a exampleSite/* . +hugo server ``` -Open config.toml file in your code editor, replace `theme = "hugo-clarity"` with `theme = ["github.com/chipzoller/hugo-clarity"]` or just `theme = "github.com/chipzoller/hugo-clarity"`. +If that seems like a lot of setup, it's meant to reduce the pain of pulling in new versions of Hugo Clarity when they are released. To pull in theme updates, run `hugo mod get -u github.com/chipzoller/hugo-clarity`. You can also update all your Hugo modules with `hugo mod get -u ./...`. [Read more about updating Hugo modules.](https://gohugo.io/hugo-modules/use-modules/#update-modules) -Hurray you can now run +> There [is more you could do with hugo modules](https://github.com/rootwork/hugo-module-site), but this will suffice for our use case here. -```yaml +### Option 3: Git submodules + +For those not ready to use Hugo modules, you can use the "old way" using git alone. + +We assume you've already run `hugo new site `, are in the `` directory, and have a working git repo (`git init`). + +1. Run: +```bash +git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity +``` +2. Hugo Clarity comes with [`exampleSite` files](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite) prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing: +```bash +cp -a themes/hugo-clarity/exampleSite/* . && rm -f config.toml +``` +If you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of [`config`](exampleSite/config/) over, as well as replacing your `archetypes/post.md` (if it exists) with [Hugo Clarity's](exampleSite/archetypes/post.md). Then migrate any necessary settings from `/config.toml` to `/config/_default/config.toml` and remove the original `/config.toml` file. +3. You can now run: +```bash hugo server ``` -To pull in theme updates, run `hugo mod get -u ./...` from the theme folder. If unsure, [learn how to update hugo modules](https://gohugo.io/hugo-modules/use-modules/#update-modules) - -> There [is more you could do with hugo modules](https://discourse.gohugo.io/t/hugo-modules-for-dummies/20758), but this will suffice for our use case here. +While this is less setup than option 2 initially, it comes with important caveats. First, to pull in new versions of the theme, you'll need to run `git submodule update --remote --merge` _and commit those changes to your git repo_. Second, if you clone your repo to another machine, have multiple people working on your site, or have a continuous-integration or deployment script (like Netlify), after cloning you'll need to also remember to run `git submodule update --init --recursive` to get the theme files. See [an overview of using git submodules for Hugo themes](https://www.andrewhoog.com/post/git-submodule-for-hugo-themes/) and [troubleshooting git submodules in Hugo themes](https://study.impl.dev/hacking/git-submodule-hugo-theme/) for details. ## Configuration -If set, jump over to the `config.toml` file and start [configuring](#configuration) your site. +Hugo Clarity uses a config folder rather than a single file. If you're used to having a `config.toml` file in your main folder, now you'll find that located in `config/_default/config.toml`, along with other settings files. This section will mainly cover settings that are unique to this theme. If something is not covered here (or elsewhere in this file), there's a good chance it is covered in [this Hugo docs page](https://gohugo.io/getting-started/configuration/#configuration-file). From e5c72703a0b4d40e8155f8b56a26ea4a21e4ec7b Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Tue, 17 May 2022 16:02:19 -0700 Subject: [PATCH 4/7] fix formatting Signed-off-by: Ivan Boothe --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 576ca698..aa48cf5b 100644 --- a/README.md +++ b/README.md @@ -138,17 +138,21 @@ This option arguably requires the least effort to run and maintain your website We assume you've already run `hugo new site ` and are in the `` directory. -1. Ensure you have the `go` binary [installed on your machine](https://golang.org/doc/install) Note: Mac users: ```brew install go```. -2. Run the following command, substituting `` with your site's name: +1. Ensure you have the `go` binary [installed on your machine](https://golang.org/doc/install). (Mac users: ```brew install go```.) + +2. Run the following command: ```bash hugo mod init ``` + 3. Hugo Clarity comes with [`exampleSite` files](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite) prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing: ```bash wget -O - https://github.com/chipzoller/hugo-clarity/archive/master.tar.gz | tar xz && cp -a hugo-clarity-master/exampleSite/* . && rm -rf hugo-clarity-master && rm -f config.toml ``` If you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of [`config`](exampleSite/config/) over, as well as replacing your `archetypes/post.md` (if it exists) with [Hugo Clarity's](exampleSite/archetypes/post.md). Then migrate any necessary settings from `/config.toml` to `/config/_default/config.toml` and remove the original `/config.toml` file. + 4. Open `/config/_default/config.toml` and change `theme = "hugo-clarity"` to `theme = ["github.com/chipzoller/hugo-clarity"]` + 5. You can now run: ```bash hugo server From beeb4b185b61e27d427226a87540e3737ddfa2e3 Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Tue, 17 May 2022 16:03:37 -0700 Subject: [PATCH 5/7] more fix formatting Signed-off-by: Ivan Boothe --- README.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index aa48cf5b..4e5f627f 100644 --- a/README.md +++ b/README.md @@ -158,9 +158,11 @@ If you do already have a site and don't want to risk overwriting anything, we su hugo server ``` -If that seems like a lot of setup, it's meant to reduce the pain of pulling in new versions of Hugo Clarity when they are released. To pull in theme updates, run `hugo mod get -u github.com/chipzoller/hugo-clarity`. You can also update all your Hugo modules with `hugo mod get -u ./...`. [Read more about updating Hugo modules.](https://gohugo.io/hugo-modules/use-modules/#update-modules) +If that seems like a lot of setup, it's meant to reduce the pain of pulling in new versions of Hugo Clarity when they are released. -> There [is more you could do with hugo modules](https://github.com/rootwork/hugo-module-site), but this will suffice for our use case here. +To pull in theme updates, run `hugo mod get -u github.com/chipzoller/hugo-clarity`. You can also update all your Hugo modules with `hugo mod get -u ./...`. [Read more about updating Hugo modules.](https://gohugo.io/hugo-modules/use-modules/#update-modules) + +> There is [more you can do with hugo modules](https://github.com/rootwork/hugo-module-site), but this will suffice for our use case here. ### Option 3: Git submodules @@ -172,11 +174,13 @@ We assume you've already run `hugo new site `, are in the `` ```bash git submodule add https://github.com/chipzoller/hugo-clarity themes/hugo-clarity ``` + 2. Hugo Clarity comes with [`exampleSite` files](https://github.com/chipzoller/hugo-clarity/tree/master/exampleSite) prefilled with helpful configuration and sample posts. If you're starting a new Hugo site and don't have any content yet, it's easiest to grab the whole thing: ```bash cp -a themes/hugo-clarity/exampleSite/* . && rm -f config.toml ``` If you do already have a site and don't want to risk overwriting anything, we suggest copying the contents of [`config`](exampleSite/config/) over, as well as replacing your `archetypes/post.md` (if it exists) with [Hugo Clarity's](exampleSite/archetypes/post.md). Then migrate any necessary settings from `/config.toml` to `/config/_default/config.toml` and remove the original `/config.toml` file. + 3. You can now run: ```bash hugo server From 2adcd0c58a4e05aebe88fd8bf007e7283c13854b Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Tue, 17 May 2022 16:05:23 -0700 Subject: [PATCH 6/7] simplification Signed-off-by: Ivan Boothe --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4e5f627f..94e31f04 100644 --- a/README.md +++ b/README.md @@ -160,7 +160,7 @@ hugo server If that seems like a lot of setup, it's meant to reduce the pain of pulling in new versions of Hugo Clarity when they are released. -To pull in theme updates, run `hugo mod get -u github.com/chipzoller/hugo-clarity`. You can also update all your Hugo modules with `hugo mod get -u ./...`. [Read more about updating Hugo modules.](https://gohugo.io/hugo-modules/use-modules/#update-modules) +To pull in theme updates, run `hugo mod get -u github.com/chipzoller/hugo-clarity`. You can also update all your Hugo modules with `hugo mod get -u ./...` -- [read more about updating Hugo modules](https://gohugo.io/hugo-modules/use-modules/#update-modules). > There is [more you can do with hugo modules](https://github.com/rootwork/hugo-module-site), but this will suffice for our use case here. @@ -186,7 +186,9 @@ If you do already have a site and don't want to risk overwriting anything, we su hugo server ``` -While this is less setup than option 2 initially, it comes with important caveats. First, to pull in new versions of the theme, you'll need to run `git submodule update --remote --merge` _and commit those changes to your git repo_. Second, if you clone your repo to another machine, have multiple people working on your site, or have a continuous-integration or deployment script (like Netlify), after cloning you'll need to also remember to run `git submodule update --init --recursive` to get the theme files. See [an overview of using git submodules for Hugo themes](https://www.andrewhoog.com/post/git-submodule-for-hugo-themes/) and [troubleshooting git submodules in Hugo themes](https://study.impl.dev/hacking/git-submodule-hugo-theme/) for details. +While this is less setup than option 2 initially, it comes with important caveats. First, to pull in new versions of the theme, you'll need to run `git submodule update --remote --merge` _and commit those changes to your git repo_. Second, if you clone your repo to another machine, have multiple people working on your site, or have a continuous-integration or deployment script (like Netlify), after cloning you'll need to also remember to run `git submodule update --init --recursive` to get the theme files. + +See [an overview of using git submodules for Hugo themes](https://www.andrewhoog.com/post/git-submodule-for-hugo-themes/) and [troubleshooting git submodules in Hugo themes](https://study.impl.dev/hacking/git-submodule-hugo-theme/) for details. ## Configuration From 66c420a9d70150bd1b595893185b008e2d329c87 Mon Sep 17 00:00:00 2001 From: Ivan Boothe Date: Wed, 18 May 2022 14:17:09 -0700 Subject: [PATCH 7/7] update min version listing Signed-off-by: Ivan Boothe --- theme.toml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/theme.toml b/theme.toml index d419fe23..d5fa81bb 100644 --- a/theme.toml +++ b/theme.toml @@ -6,10 +6,11 @@ homepage = "https://github.com/chipzoller/hugo-clarity" demosite = "https://neonmirrors.net/" tags = ["blog", "technical", "simple", "dark", "syntax highlighting"] features = ["blog", "technical", "simple", "dark", "syntax highlighting"] -min_version = "0.63.0" +min_version = "0.91.0" # If the theme has multiple authors authors = [ {name = "Chip Zoller", homepage = "https://neonmirrors.net"}, {name = "Dan Weru", homepage = "https://github.com/onweru"}, + {name = "Ivan Boothe", homepage = "https://rootwork.org"}, ]