diff --git a/exampleSite/content/docs/getting-started.md b/exampleSite/content/docs/getting-started.md index af1b3ede..d4271f8e 100644 --- a/exampleSite/content/docs/getting-started.md +++ b/exampleSite/content/docs/getting-started.md @@ -19,18 +19,29 @@ We have provided a [GitHub Actions workflow](https://docs.github.com/en/pages/ge ## Start as New Project -### Prerequisites +There are two main ways to add the Hextra theme to your Hugo project. -Before we start, make sure we have [Hugo](https://gohugo.io/) installed. -Please refer to Hugo's [official installation guide](https://gohugo.io/installation/) for more details. +1. **Hugo Modules (Recommended)**: The simplest and recommended method. [Hugo modules](https://gohugo.io/hugo-modules/) let you pull in the theme directly from its online source. Theme is downloaded automatically and managed by Hugo. -[Hugo modules](https://gohugo.io/hugo-modules/) are the recommended way to manage Hugo themes. To use Hugo modules, we need to install [Git](https://git-scm.com/) and [Go](https://go.dev/). +2. **Git Submodule**: Alternatively, add Hextra as a [Git Submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). The theme will be downloaded by Git and stored in your project's `themes` folder. + +### Setup Hextra as Hugo module + +#### Prerequisites + +Before starting, you need to have the following softwares installed: + +- [Hugo (extended version)](https://gohugo.io/installation/) +- [Git](https://git-scm.com/) +- [Go](https://go.dev/) + +#### Steps {{% steps %}} ### Initialize a new Hugo site -```bash +```shell $ hugo new site my-site --format=yaml ``` @@ -45,7 +56,7 @@ $ hugo mod init github.com/username/my-site $ hugo mod get github.com/imfing/hextra ``` -Edit `hugo.yaml` to enable Hextra theme: +Configure `hugo.yaml` to use Hextra theme by adding the following: ```yaml module: @@ -55,7 +66,7 @@ module: ### Create your first content pages -Let's create a new content page for the home page and the documentation page: +Let's create new content page for the home page and the documentation page: ```shell $ hugo new content/_index.md @@ -73,20 +84,101 @@ Voila! You can see your new site at `http://localhost:1313/`. {{% /steps %}} -## Update Theme - {{% details title="How to update theme?" %}} -To update the theme to the [latest released version](https://github.com/imfing/hextra/releases), run the following command: +To update all Hugo modules in your project to their latest versions, run the following command: ```shell $ hugo mod get -u ``` +To update only Hextra to the [latest released version](https://github.com/imfing/hextra/releases), run the following command: + +```shell +hugo mod get -u github.com/imfing/hextra +``` + See [Hugo Modules](https://gohugo.io/hugo-modules/use-modules/#update-all-modules) for more details. {{% /details %}} +### Setup Hextra as Git submodule + +#### Prerequisites + +Before starting, you need to have the following softwares installed: + +- [Hugo (extended version)](https://gohugo.io/installation/) +- [Git](https://git-scm.com/) + +#### Steps + +{{% steps %}} + +### Initialize a new Hugo site + +```shell +$ hugo new site my-site --format=yaml +``` + +### Add Hextra theme as a Git submodule + +```shell +git submodule add https://github.com/imfing/hextra.git themes/hextra +``` + +Configure `hugo.yaml` to use Hextra theme by adding the following: + +```yaml +theme: hextra +``` + +### Create your first content pages + +Let's create new content page for the home page and the documentation page: + +```shell +$ hugo new content/_index.md +$ hugo new content/docs/_index.md +``` + +### Preview the site locally + +```shell +$ hugo server --buildDrafts --disableFastRender +``` + +Voila! You can see your new site at `http://localhost:1313/`. + +{{% /steps %}} + + +When using [CI/CD](https://en.wikipedia.org/wiki/CI/CD) for Hugo website deployment, it's essential to ensure that the following command is executed before running the `hugo` command. + +```shell +git submodule update --init +``` + +Failure to run this command will result in the theme folder not being populated with Hextra theme files, leading to a build failure. + + +{{% details title="How to update theme?" %}} + +To update all submodules in your repository to their latest commits, run the following command: + +```shell +$ git submodule update --remote +``` + +To update only Hextra to the latest commit, run the following command: + +```shell +git submodule update --remote themes/hextra +``` + +See [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more details. + +{{% /details %}} ## Next