add getting started guide
This commit is contained in:
parent
8ea9b3e092
commit
953d541bfe
GPG Key ID:
65362AE74AF98B61
33
README.md
33
README.md
|
|
@ -1,18 +1,33 @@
|
|||
# Hugo Geekblog Theme
|
||||
# Geekblog
|
||||
|
||||
[](https://cloud.drone.io/xoxys/hugo-geekblog)
|
||||
[](https://gohugo.io)
|
||||
[](https://github.com/xoxys/hugo-geekblog/releases/latest)
|
||||
[](LICENSE)
|
||||
[](https://github.com/xoxys/hugo-geekblog/graphs/contributors)
|
||||
[](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).
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
## Maintainers and Contributors
|
||||
|
||||
[Robert Kaussow](https://github.com/xoxys)
|
||||
This project is licensed under the MIT License - see the [LICENSE](https://github.com/xoxys/hugo-geekblog/blob/master/LICENSE) file for details.
|
||||
|
|
|
|||
|
|
@ -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-->
|
||||
|
||||
[](https://cloud.drone.io/xoxys/hugo-geekblog)
|
||||
[](https://gohugo.io)
|
||||
[](https://github.com/xoxys/hugo-geekblog/releases/latest)
|
||||
[](https://github.com/xoxys/hugo-geekblog/graphs/contributors)
|
||||
[](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
|
||||
|
|
@ -7,7 +7,6 @@ authors:
|
|||
tags:
|
||||
- Open Source
|
||||
- Development
|
||||
- DevOps
|
||||
resources:
|
||||
- name: testimage
|
||||
src: 'images/testimage.jpg'
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue