[skip ci] improve getting started documentation

This commit is contained in:
Robert Kaussow 2020-09-12 11:57:41 +02:00
parent 862d2742fb
commit f4a3018d47
No known key found for this signature in database
GPG key ID: 65362AE74AF98B61
9 changed files with 146 additions and 3 deletions

View file

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

View file

@ -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).

View file

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

View file

@ -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

View file

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

View file

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

View file

@ -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
```

12
package-lock.json generated
View file

@ -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",

View file

@ -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": [