From 6641d36b984ac9e50648a498612514fdba8ce7bb Mon Sep 17 00:00:00 2001
From: Sid <122173059+hugo-sid@users.noreply.github.com>
Date: Mon, 16 Oct 2023 18:58:28 +0530
Subject: [PATCH] docs: add using Hextra as Git submodule (#137)

* docs: update docs relating to getting started and Hugo modules

* docs: add docs to use Hextra as Git submodule, closes #107

* chore: use paragraph instead of callout, refactor docs

* Update getting-started.md

* Update getting-started.md

---------

Co-authored-by: Xin <xin@imfing.com>
---
 exampleSite/content/docs/getting-started.md | 112 ++++++++++++++++++--
 1 file changed, 102 insertions(+), 10 deletions(-)

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