add getting started guide

README.md

@@ -1,18 +1,33 @@
-# Hugo Geekblog Theme
+# Geekblog
 
 [![Build Status](https://img.shields.io/drone/build/xoxys/hugo-geekblog?logo=drone)](https://cloud.drone.io/xoxys/hugo-geekblog)
 [![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-geekblog)](https://github.com/xoxys/hugo-geekblog/releases/latest)
-[![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekblog)](LICENSE)
+[![GitHub contributors](https://img.shields.io/github/contributors/xoxys/hugo-geekblog)](https://github.com/xoxys/hugo-geekblog/graphs/contributors)
+[![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekblog)](https://github.com/xoxys/hugo-geekblog/blob/master/LICENSE)
 
-geekblog is a simple Hugo theme for personal blogs. This work is inspired and partially based on the [hugo-book](https://github.com/alex-shpak/hugo-book) theme. You can find a demo and the full documentation at [https://hugo-geekblog.geekdocs.de](https://hugo-geekblog.geekdocs.de).
+Geekblog is a simple Hugo theme for personal blogs. It is intentionally designed as a fast and lean theme and may not fit the requirements for more complex websites. 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://hugo-geekblog.geekdocs.de](https://hugo-geekblog.geekdocs.de).
 
-![Screenshot](https://github.com/xoxys/hugo-geekblog/blob/master/images/screenshot.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-geekblog/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://hugo-geekblog.geekdocs.de/posts/getting-started/) for details about the different setup options.
+
+## Contributors
+
+Special thanks goes to all [contributors](https://github.com/xoxys/hugo-geekblog/graphs/contributors).
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/xoxys/hugo-geekblog/blob/master/LICENSE) file for details.
-
-## Maintainers and Contributors
-
-[Robert Kaussow](https://github.com/xoxys)

exampleSite/content/posts/getting-started.md

@@ -1,5 +1,5 @@
 ---
-title: "How to use the theme"
+title: "Getting Started"
 date: 2020-07-15T20:00:00+02:00
 authors:
   - john-doe
@@ -8,17 +8,20 @@ tags:
 weight: 1
 ---
 
-This post works as a documentation for the features of the theme.
+This post tells you how to get started with the Geekblog theme, including installation and basic configuration.
 
 <!--more-->
 
 [![Build Status](https://img.shields.io/drone/build/xoxys/hugo-geekblog?logo=drone)](https://cloud.drone.io/xoxys/hugo-geekblog)
 [![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-geekblog)](https://github.com/xoxys/hugo-geekblog/releases/latest)
+[![GitHub contributors](https://img.shields.io/github/contributors/xoxys/hugo-geekblog)](https://github.com/xoxys/hugo-geekblog/graphs/contributors)
 [![License: MIT](https://img.shields.io/github/license/xoxys/hugo-geekblog)](https://github.com/xoxys/hugo-geekblog/blob/master/LICENSE)
 
 <!-- spellchecker-disable -->
+
 {{< toc >}}
+
 <!-- spellchecker-enable -->
 
 ## Features
@@ -33,6 +36,97 @@ This post works as a documentation for the features of the theme.
 - Multiple authors
 - Supports Atom and JSON feeds
 
+## Install requirements
+
+You need a recent version of Hugo for local builds and previews of sites that use Geekblog. 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 Geekblog 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 = "Geekblog"
+   theme = "hugo-geekblog"
+
+   # Geekblog 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 geekblog -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-geekblog/releases/latest/download/hugo-geekblog.tar.gz | tar -xz -C themes/hugo-geekblog/ --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 Geekblog git repository.
+
+```Shell
+git clone https://github.com/xoxys/hugo-geekblog.git themes/geekblog
+```
+
+Build required theme assets e.g. CSS files and SVG sprites with `gulp`.
+
+```Shell
+gulp default
+```
+
 ## Configuration
 
 ### Site configuration
@@ -262,7 +356,7 @@ weight = 1
 authors = ["john-doe"]
 
 # Tags for this post.
-tags = ["Open Source", "DevOps"]
+tags = ["Open Source"]
 
 # Set how many table of contents levels to be showed on page.
 geekblogToC = 3
@@ -291,7 +385,6 @@ authors:
 # Tags for this post.
 tags:
   - Open Source
-  - DevOps
 
 # Set how many table of contents levels to be showed on page.
 geekblogToC: 3

exampleSite/content/posts/post-with-images/index.md

@@ -7,7 +7,6 @@ authors:
 tags:
   - Open Source
   - Development
-  - DevOps
 resources:
   - name: testimage
     src: 'images/testimage.jpg'

exampleSite/content/posts/sticky.md

@@ -6,7 +6,6 @@ authors:
   - john-doe
 tags:
   - Open Source
-  - DevOps
 ---
 
 Sticky (or pinned) posts implementation is currently really simple and handled by `weight: 1` in a post front matter.