[skip ci] improve getting started documentation

.dictionary

@@ -7,3 +7,6 @@ ToC
 macOS
 SVG
 HC-primary
+pre-processor
+pre-build
+submodule

README.md

@@ -4,12 +4,28 @@
 [![Hugo Version](https://img.shields.io/badge/hugo-0.65-blue.svg)](https://gohugo.io)
 [![GitHub release](https://img.shields.io/github/v/release/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/releases/latest)
 [![GitHub contributors](https://img.shields.io/github/contributors/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/graphs/contributors)
-[![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekdoc)](LICENSE)
+[![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/blob/master/LICENSE)
 
 Geekdoc is a simple Hugo theme for documentations. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. You can find a demo and the full documentation at [https://geekdocs.de](https://geekdocs.de).
 
 ![Desktop and mobile preview](https://github.com/xoxys/hugo-geekdoc/blob/master/images/readme.png)
 
+## Build and release process
+
+This theme is subject to a CI driven build and release process common for software development. During the release build, all necessary assets are automatically built by [gulp](https://gulpjs.com/) and bundled in a release tarball. You can download the latest release from the [GitHub release page](https://github.com/xoxys/hugo-geekdoc/releases).
+
+Due to the fact that `gulp` is used as pre-processor the theme cannot be used from the master branch by default. If you want to use the theme from a cloned branch instead of a release tarball you'll need to install `gulp` locally and run the default pipeline once to create all required assets.
+
+```Shell
+# install required packages from package.json
+npm install
+
+# run gulp pipeline to build required assets
+gulp default
+```
+
+See the [Getting Started Guide](https://geekdocs.de/usage/getting_started/) for details about the different setup options.
+
 ## Contributors
 
 Special thanks goes to all [contributors](https://github.com/xoxys/hugo-geekdoc/graphs/contributors).

exampleSite/config.yaml

@@ -9,7 +9,7 @@ pygmentsCodeFences: true
 disablePathToLower: true
 enableGitInfo: true
 
-# Needed for mermaid/katex shortcodes
+# Needed for mermaid shortcodes
 markup:
   goldmark:
     renderer:

exampleSite/content/_index.md

@@ -5,9 +5,10 @@ title: Documentation
 [![Build Status](https://img.shields.io/drone/build/xoxys/hugo-geekdoc?logo=drone)](https://cloud.drone.io/xoxys/hugo-geekdoc)
 [![Hugo Version](https://img.shields.io/badge/hugo-0.65-blue.svg)](https://gohugo.io)
 [![GitHub release](https://img.shields.io/github/v/release/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/releases/latest)
+[![GitHub contributors](https://img.shields.io/github/contributors/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/graphs/contributors)
 [![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekdoc)](https://github.com/xoxys/hugo-geekdoc/blob/master/LICENSE)
 
-Geekdoc is a simple Hugo theme for documentations. This work is inspired and partially based on the [hugo-book](https://github.com/alex-shpak/hugo-book) theme.
+Geekdoc is a simple Hugo theme for documentations. It is intentionally designed as a fast and lean theme and may not fit the requirements of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. You can find a demo and the full documentation at [https://geekdocs.de](https://geekdocs.de).
 
 ## Features
 

exampleSite/content/usage/_index.md

@@ -1,3 +1,4 @@
 ---
 title: Usage
+weight: -10
 ---

exampleSite/content/usage/configuration.md

@@ -1,3 +1,8 @@
+---
+title: Configuration
+weight: -10
+---
+
 ## Site configuration
 
 {{< tabs "site-config" >}}

exampleSite/content/usage/getting_started.md

@@ -0,0 +1,103 @@
+---
+title: Getting Started
+weight: -20
+---
+
+This page tells you how to get started with the Geekdoc theme, including installation and basic configuration.
+
+<!-- spellchecker-disable -->
+
+{{< toc >}}
+
+<!-- spellchecker-enable -->
+
+## Install requirements
+
+You need a recent version of Hugo for local builds and previews of sites that use Geekdoc. As we are using [gulp](https://gulpjs.com/) as pre-processor the normal version of Hugo is sufficient. If you prefer the extended version of Hugo anyway this will work as well. For comprehensive Hugo documentation, see [gohugo.io](https://gohugo.io/documentation/).
+
+If you want to use the theme from a cloned branch instead of a release tarball you'll need to install `gulp` locally and run the default pipeline once to create all required assets.
+
+```Shell
+# install required packages from package.json
+npm install
+
+# run gulp pipeline to build required assets
+gulp default
+```
+
+## Using the theme
+
+To prepare your new site environment just a few steps are required:
+
+1. Create a new empty Hugo site.
+
+   ```Shell
+   hugo new site demosite
+   ```
+
+2. Switch to the root of the new site.
+
+   ```Shell
+   cd demosite
+   ```
+
+3. Install the Geekdoc theme from a [release bundle](#option-1-download-pre-build-release) (recommended) or form [Git branch](#option-2-clone-the-github-repository).
+
+4. Create the minimal required Hugo configuration `config.toml`. For all configuration options see [here](/usage/configuration/).
+
+   ```Toml
+   baseURL = "http://localhost"
+   title = "Geekdocs"
+   theme = "hugo-geekdoc"
+
+   # Geekdoc required configuration
+   pygmentsUseClasses = true
+   pygmentsCodeFences = true
+
+   disablePathToLower = true
+   enableGitInfo=true
+
+   # Needed for mermaid shortcodes
+   [markup]
+     [markup.goldmark.renderer]
+       # Needed for mermaid shortcode
+       unsafe = true
+     [markup.tableOfContents]
+       startLevel = 1
+       endLevel = 9
+   ```
+
+5. Test your site.
+
+   ```Shell
+   hugo server --theme geekdoc -D
+   ```
+
+### Option 1: Download pre-build release bundle
+
+Download and extract the latest release bundle into the theme directory.
+
+```Shell
+curl -L https://github.com/xoxys/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1
+```
+
+### Option 2: Clone the GitHub repository
+
+{{< hint info >}}
+**Info**\
+Keep in mind this method is not recommended and needs some extra steps to get it working.
+If you want to use the Theme as submodule keep in mind that your build process need to
+run the described steps as well.
+{{< /hint >}}
+
+Clone the Geekdoc git repository.
+
+```Shell
+git clone https://github.com/xoxys/hugo-geekdoc.git themes/geekdoc
+```
+
+Build required theme assets e.g. CSS files and SVG sprites with `gulp`.
+
+```Shell
+gulp default
+```

package-lock.json

@@ -5235,6 +5235,18 @@
       "integrity": "sha512-LmeoohTpp/K4UiyQCwuGWlONxXamGzCMtFxLq4W1nZVGIQLYvMCJx3yAF9qyyuFpflABI9yVdtJAqbihOsCsJQ==",
       "dev": true
     },
+    "prettier": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.1.1.tgz",
+      "integrity": "sha512-9bY+5ZWCfqj3ghYBLxApy2zf6m+NJo5GzmLTpr9FsApsfjriNnS2dahWReHMi7qNPhhHl9SYHJs2cHZLgexNIw==",
+      "dev": true
+    },
+    "prettier-plugin-go-template": {
+      "version": "0.0.10",
+      "resolved": "https://registry.npmjs.org/prettier-plugin-go-template/-/prettier-plugin-go-template-0.0.10.tgz",
+      "integrity": "sha512-TaHPqiMK/zfk+YhvKRf/1WZDgQ6ffnlxJZX5rwphqfxBOVEezZQtYistTB348MKrKnnwKpyXZWpMRo0/KCVB+A==",
+      "dev": true
+    },
     "pretty-hrtime": {
       "version": "1.0.3",
       "resolved": "https://registry.npmjs.org/pretty-hrtime/-/pretty-hrtime-1.0.3.tgz",

package.json

@@ -23,6 +23,8 @@
     "gulp-rename": "^2.0.0",
     "gulp-sass": "^4.1.0",
     "gulp-svg-sprite": "^1.5.0",
+    "prettier": "^2.1.1",
+    "prettier-plugin-go-template": "0.0.10",
     "run-sequence": "^2.2.1"
   },
   "browserslist": [