[skip ci] improve getting started documentation
This commit is contained in:
Robert Kaussow
parent
862d2742fb
commit
f4a3018d47
9 changed files with 146 additions and 3 deletions
|
|
@ -7,3 +7,6 @@ ToC
|
|||
macOS
|
||||
SVG
|
||||
HC-primary
|
||||
pre-processor
|
||||
pre-build
|
||||
submodule
|
||||
|
|
|
|||
18
README.md
18
README.md
|
|
@ -4,12 +4,28 @@
|
|||
[](https://gohugo.io)
|
||||
[](https://github.com/xoxys/hugo-geekdoc/releases/latest)
|
||||
[](https://github.com/xoxys/hugo-geekdoc/graphs/contributors)
|
||||
[](LICENSE)
|
||||
[](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).
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ pygmentsCodeFences: true
|
|||
disablePathToLower: true
|
||||
enableGitInfo: true
|
||||
|
||||
# Needed for mermaid/katex shortcodes
|
||||
# Needed for mermaid shortcodes
|
||||
markup:
|
||||
goldmark:
|
||||
renderer:
|
||||
|
|
|
|||
|
|
@ -5,9 +5,10 @@ title: Documentation
|
|||
[](https://cloud.drone.io/xoxys/hugo-geekdoc)
|
||||
[](https://gohugo.io)
|
||||
[](https://github.com/xoxys/hugo-geekdoc/releases/latest)
|
||||
[](https://github.com/xoxys/hugo-geekdoc/graphs/contributors)
|
||||
[](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
|
||||
|
||||
|
|
|
|||
|
|
@ -1,3 +1,4 @@
|
|||
---
|
||||
title: Usage
|
||||
weight: -10
|
||||
---
|
||||
|
|
|
|||
|
|
@ -1,3 +1,8 @@
|
|||
---
|
||||
title: Configuration
|
||||
weight: -10
|
||||
---
|
||||
|
||||
## Site configuration
|
||||
|
||||
{{< tabs "site-config" >}}
|
||||
|
|
|
|||
103
exampleSite/content/usage/getting_started.md
Normal file
103
exampleSite/content/usage/getting_started.md
Normal 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
12
package-lock.json
generated
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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": [
|
||||
|
|
|
|||
Loading…
Reference in a new issue