github/hugo-geekblog
0
0
Fork 0
mirror of https://github.com/thegeeklab/hugo-geekblog.git synced 2024-11-22 05:00:39 +00:00
Code Issues Projects Releases Wiki Activity

docs: improve documentation structure (#94)

Browse Source
This commit is contained in:
Robert Kaussow 2021-09-23 12:01:54 +02:00 committed by GitHub
parent 09639006d9
commit d0cab9622b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 748 additions and 677 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
exampleSite/content/posts/mermaid.md → exampleSite/content/posts/advanced/mermaid.md
View File

@ -6,7 +6,6 @@ authors:
tags: tags:
- Documentation - Documentation
- Shortcodes - Shortcodes
weight: 10
--- ---
[Mermaid](https://mermaidjs.github.io/) is library for generating SVG charts and diagrams from text. [Mermaid](https://mermaidjs.github.io/) is library for generating SVG charts and diagrams from text.

12
exampleSite/content/posts/shortcodes.md → exampleSite/content/posts/advanced/shortcodes.md
View File

@ -7,7 +7,6 @@ tags:
- Documentation - Documentation
- Shortcodes - Shortcodes
geekblogToC: 1 geekblogToC: 1
weight: 5
--- ---
<!-- markdownlint-disable MD024 --> <!-- markdownlint-disable MD024 -->
@ -22,6 +21,7 @@ The theme bundles some handy shortcodes that tries to cover common situations.
Buttons are styled links that can lead to local page or external link. Buttons are styled links that can lead to local page or external link.
<!-- prettier-ignore -->
```tpl ```tpl
{{</* button relref="/" [class="...", size="large|regular"] */>}}Get Home{{</* /button */>}} {{</* button relref="/" [class="...", size="large|regular"] */>}}Get Home{{</* /button */>}}
{{</* button href="https://github.com/thegeeklab/hugo-geekblog" */>}}Contribute{{</* /button */>}} {{</* button href="https://github.com/thegeeklab/hugo-geekblog" */>}}Contribute{{</* /button */>}}
@ -36,6 +36,7 @@ Buttons are styled links that can lead to local page or external link.
The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability. The Columns shortcode can be used to organize content side-by-side (horizontally) for better readability.
<!-- prettier-ignore -->
```html ```html
{{</* columns */>}} <!-- begin columns block --> {{</* columns */>}} <!-- begin columns block -->
# Left Content # Left Content
@ -102,15 +103,15 @@ The above steps enable Unicode Standard emoji characters and sequences in Hugo,
**Styling:** **Styling:**
<!-- prettier-ignore-start -->
<!-- spellchecker-disable --> <!-- spellchecker-disable -->
<!-- prettier-ignore -->
{{< highlight html "linenos=table" >}} {{< highlight html "linenos=table" >}}
.emoji { .emoji {
font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols; font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
} }
{{< /highlight >}} {{< /highlight >}}
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
<!-- prettier-ignore-end -->
## Expand ## Expand
@ -120,6 +121,7 @@ Expand shortcode can help to decrease clutter on screen by hiding part of text.
#### Default #### Default
<!-- prettier-ignore -->
```tpl ```tpl
{{</* expand */>}} {{</* expand */>}}
## Markdown content ## Markdown content
@ -136,6 +138,7 @@ Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclima
#### With Custom Label #### With Custom Label
<!-- prettier-ignore -->
```tpl ```tpl
{{</* expand "Custom Label" "..." */>}} {{</* expand "Custom Label" "..." */>}}
## Markdown content ## Markdown content
@ -158,6 +161,7 @@ copious quo ad. Stet probates in duo.
Hint shortcode can be used as hint/alerts/notification block. Hint shortcode can be used as hint/alerts/notification block.
There are four colors to choose: `info`, `ok`, `warning` and `danger`. There are four colors to choose: `info`, `ok`, `warning` and `danger`.
<!-- prettier-ignore -->
```tpl ```tpl
{{</* hint [info|warning|danger] */>}} {{</* hint [info|warning|danger] */>}}
**Markdown content**\ **Markdown content**\
@ -196,6 +200,7 @@ Ornateness bland it ex enc, est yeti am bongo detract re.
Simple shortcode to include icons from SVG sprites outside of menus. Simple shortcode to include icons from SVG sprites outside of menus.
<!-- prettier-ignore -->
```tpl ```tpl
{{</* icon "thumbs-up" */>}} {{</* icon "thumbs-up" */>}}
``` ```
@ -214,6 +219,7 @@ Simple shortcode to include icons from SVG sprites outside of menus.
Tabs let you organize content by context, for example installation instructions for each supported platform. Tabs let you organize content by context, for example installation instructions for each supported platform.
<!-- prettier-ignore -->
```tpl ```tpl
{{</* tabs "uniqueid" */>}} {{</* tabs "uniqueid" */>}}
{{</* tab "macOS" */>}} # macOS Content {{</* /tab */>}} {{</* tab "macOS" */>}} # macOS Content {{</* /tab */>}}

6
exampleSite/content/posts/toc.md → exampleSite/content/posts/advanced/toc.md
View File

@ -1,16 +1,18 @@
--- ---
title: ToC title: Table of Content
date: 2021-05-23T20:00:00+01:00 date: 2021-05-23T20:00:00+01:00
authors: authors:
- john-doe - john-doe
tags: tags:
- Documentation - Documentation
- Shortcodes - Shortcodes
weight: 10
--- ---
Simple wrapper to generate a page Table of Content from a shortcode. Simple wrapper to generate a page Table of Content from a shortcode.
<!--more-->
<!-- prettier-ignore -->
```tpl ```tpl
{{</* toc */>}} {{</* toc */>}}
``` ```

80
exampleSite/content/posts/deployments.md
View File

@ -1,80 +0,0 @@
---
title: Deployments
date: 2021-05-23T20:00:00+01:00
authors:
- john-doe
tags:
- Documentation
- Shortcodes
weight: 5
---
{{< toc >}}
## Netlify
There are several ways to deploy your site with this theme on Netlify. Regardless of which solution you choose, the main goal is to ensure that the prebuilt theme release tarball is used or to run the [required commands](/posts/getting-started/#option-2-clone-the-github-repository) to prepare the theme assets before running the Hugo build command.
Here are some possible solutions:
**Use a Makefile:**
Add a Makefile to your repository to bundle the required steps.
```Makefile
THEME_VERSION := v0.8.2
THEME := hugo-geekblog
BASEDIR := docs
THEMEDIR := $(BASEDIR)/themes
.PHONY: doc
doc: doc-assets doc-build
.PHONY: doc-assets
doc-assets:
mkdir -p $(THEMEDIR)/$(THEME)/ ; \
curl -sSL "https://github.com/thegeeklab/$(THEME)/releases/download/${THEME_VERSION}/$(THEME).tar.gz" | tar -xz -C $(THEMEDIR)/$(THEME)/ --strip-components=1
.PHONY: doc-build
doc-build:
cd $(BASEDIR); hugo
.PHONY: clean
clean:
rm -rf $(THEMEDIR) && \
rm -rf $(BASEDIR)/public
```
This Makefile can be used in your `netlify.toml`, take a look at the Netlify [example](https://docs.netlify.com/configure-builds/file-based-configuration/#sample-file) for more information:
```toml
[build]
publish = "docs/public"
command = "make doc"
```
**Chain required commands:**
Chain all required commands to prepare the theme and build your site on the `command` option in your `netlify.toml` like this:
```toml
[build]
publish = "docs/public"
command = "command1 && command 2 && command3 && hugo"
```
## Subdirectories
{{< hint danger >}}
**Warning**\
As deploying Hugo sites on subdirectories is not as robust as on subdomains, we do not recommend this.
If you have a choice, using a domain/subdomain should always be the preferred solution!
{{< /hint >}}
If you want to deploy your side to a subdirectory of your domain, some extra steps are required:
- Configure your Hugo base URL e.g. `baseURL = http://localhost/demo/`.
- Don't use `relativeURLs: false` nor `canonifyURLs: true` as is can cause unwanted side effects!
There are two ways to get Markdown links or images working:
- Use the absolute path including your subdirectory e.g. `[testlink](/demo/example-site)`
- Overwrite the HTML base in your site configuration with `geekblogOverwriteHTMLBase = true` and use the relative path e.g. `[testlink](example-site)`
But there is another special case if you use `geekblogOverwriteHTMLBase = true`. If you use anchors in your Markdown links you have to ensure to always include the page path. As an example `[testlink](#some-anchor)` will resolve to `http://localhost/demo/#some-anchor` and not automatically include the current page!

41
exampleSite/content/posts/features/authors.md Normal file
View File

@ -0,0 +1,41 @@
---
title: Authors
date: 2021-05-23T20:00:00+01:00
authors:
- john-doe
tags:
- Documentation
- Features
---
The theme supports multiple authors. The required information for each author need to be stored in a single [Hugo data template](https://gohugo.io/templates/data-templates/) per author.These files need to be stored in the `data/authors/` directory in your projects root.
<!--more-->
```Shell
data/
└── authors
├── john-doe.yml
├── richard-roe.yml
└── Special User.yml
```
The name of the file will be used as the reference later, so if you prefer some kind of naming convention this need to covered by the file names. Example authors file:
```YAML
name: John Doe
email: john@example.com
```
With the defined files, you can add as many authors as you want to the front matter of your posts:
```Markdown
---
title: Demo Posts
authors:
- john-doe
- Special User
---
My first demo post.
```

58
exampleSite/content/posts/features/icon-sets.md Normal file
View File

@ -0,0 +1,58 @@
---
title: Icon Sets
date: 2021-05-23T20:00:00+01:00
authors:
- john-doe
tags:
- Documentation
- Features
---
Learn how about build-in icons and how to extend it.
<!--more-->
{{< toc >}}
## Custom icons
The only supported source for custom icons are SVG sprites. Some icon frameworks provides ready to use sprites e.g. FontAwesome. If the framework don't provide sprites, you can create your own from raw SVG icons. There are a lot of tools available to create sprites, please choose one that fits your need. One solution could be [svgsprit.es](https://svgsprit.es/).
Regardless of which tool (or existing sprite) you choose, there are a few requirements that must be met:
1. The sprite must be a valid **SVG** file.
2. You have to ensure to **hide the sprite**. Apply the predefined class `svg-sprite` or `hidden` to the root element of your sprite or add a small piece of inline CSS e.g. `style="display: none;"`.
3. Save the sprite to the folder `assets/sprites` right beside your `content` folder.
The result of a valid minimal SVG sprite file could look like this:
```XML
<svg class="svg-sprite" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<symbol viewBox="-2.29 -2.29 28.57 28.57" id="arrow_back" xmlns="http://www.w3.org/2000/svg">
<path d="M24 10.526v2.947H5.755l8.351 8.421-2.105 2.105-12-12 12-12 2.105 2.105-8.351 8.421H24z"/>
</symbol>
</svg>
```
**Example:**
FontAwesome provides three pre-build sprites included in the regular Web download pack, `sprites/brands.svg`, `sprites/regular.svg` and `sprites/solid.svg`. Choose your sprite to use and copy it to your projects root directory into `assets/sprites`, right beside your `content` folder. The result should look like this:
```Bash
my_projcet/
├── assets
│ └── sprites
│ └── regular.svg
├── config.yaml
├── content
│ ├── _index.md
│ ├── ...
```
That's it! The theme will auto-load all available SVG sprites provided in the assets folder. To use the icons, you need to lookup the id of the icon. An example would be `thumbs-up` {{< icon "thumbs-up" >}}. There is also a [shortcode](/posts/advanced/shortcodes/#icon) available
## Build-in icons
The theme bundles just a small set of hand crafted icons.
{{< sprites >}}

24
exampleSite/content/posts/features/sticky.md Normal file
View File

@ -0,0 +1,24 @@
---
title: Simple sticky posts
date: 2020-06-13T00:06:00+02:00
authors:
- john-doe
tags:
- Documentation
- Features
weight: 1
---
Sticky (or pinned) posts can be used to permanently pin important posts to the top of the post list. The implementation is pretty simple and handled by `weight: 1` in a post front matter. As there is no other logic to identify sticky posts you should not use negative values for weight as this will result in posts listed earlier.
**Example:**
```YAML
---
title: Simple sticky posts
weight: 1
date: 2020-06-13T00:06:00+02:00
authors:
- john-doe
---
```

575
exampleSite/content/posts/getting-started.md
View File

@ -1,575 +0,0 @@
---
title: Getting Started
date: 2020-07-15T20:00:00+02:00
authors:
- john-doe
- Special User
tags:
- Documentation
weight: 1
---
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 of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. This post helps you to get started with the Geekblog theme, including initial setup and basic configuration.
<!--more-->
[![Build Status](https://img.shields.io/drone/build/thegeeklab/hugo-geekblog?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/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/thegeeklab/hugo-geekblog)](https://github.com/thegeeklab/hugo-geekblog/releases/latest)
[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/hugo-geekblog)](https://github.com/thegeeklab/hugo-geekblog/graphs/contributors)
[![License: MIT](https://img.shields.io/github/license/thegeeklab/hugo-geekblog)](https://github.com/thegeeklab/hugo-geekblog/blob/main/LICENSE)
{{< toc >}}
## Features
- Clean and simple design
- Light and mobile-friendly
- Easy customization
- Zero initial configuration
- Handy shortcodes
- Simple sticky posts
- Content tags
- 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
npx 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-bundle) (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](#configuration).
```Toml
baseURL = "http://localhost"
title = "Geekblog"
theme = "hugo-geekblog"
pluralizeListTitles = false
# Geekblog required configuration
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
# Needed for mermaid shortcodes
[markup]
[markup.goldmark.renderer]
unsafe = true
[markup.tableOfContents]
startLevel = 1
endLevel = 9
[taxonomies]
author = "authors"
tag = "tags"
[mediaTypes]
[mediaTypes."application/atom+xml"]
suffixes = ["xml"]
[outputFormats]
[outputFormats.Atom]
name = "Atom"
mediaType = "application/atom+xml"
baseName = "feed"
isPlainText = false
rel = "alternate"
isHTML = false
noUgly = true
permalinkable = false
[outputs]
home = ["HTML", "ATOM"]
page = ["HTML"]
section = ["HTML"]
taxonomy = ["HTML"]
term = ["HTML", "ATOM"]
```
5. Test your site.
```Shell
hugo server -D
```
If you want to add some demo data you could use the content from the [Hugo basic example](https://github.com/gohugoio/hugoBasicExample):
```Shell
curl -L https://github.com/gohugoio/hugoBasicExample/archive/main.tar.gz | tar -xz --exclude "config*" --exclude "LICENSE" --exclude "README*" --strip-components=1
```
### Option 1: Download pre-build release bundle
Download and extract the latest release bundle into the theme directory.
```Shell
mkdir -p themes/hugo-geekblog/
curl -L https://github.com/thegeeklab/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/thegeeklab/hugo-geekblog.git themes/geekblog
```
Build required theme assets e.g. CSS files and SVG sprites with `gulp`.
```Shell
npx gulp default
```
## Configuration
### Site configuration
{{< tabs "site-config" >}}
{{< tab "TOML" >}}
```Toml
baseURL = "http://localhost"
title = "Geekblog"
theme = "hugo-geekblog"
paginate = 5
pluralizeListTitles = false
# Required to get well formatted code blocks
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
enableGitInfo = true
# Required if you want to render robots.txt template
enableRobotsTXT = true
[markup]
[markup.goldmark.renderer]
unsafe = true
[markup.tableOfContents]
startLevel = 1
endLevel = 9
[taxonomies]
author = "authors"
tag = "tags"
[mediaTypes]
[mediaTypes."application/atom+xml"]
suffixes = ["xml"]
[outputFormats]
[outputFormats.Atom]
# https://validator.w3.org/feed/docs/atom.html#whatIsAtom
name = "Atom"
mediaType = "application/atom+xml"
# generated file = <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
baseName = "feed"
isPlainText = false
rel = "alternate"
isHTML = false
noUgly = true
permalinkable = false
[outputs]
home = ["HTML", "ATOM"]
page = ["HTML"]
section = ["HTML"]
taxonomy = ["HTML"]
term = ["HTML", "ATOM"]
[params]
subtitle = "Blog about my favorite topics"
description = "This is my personal blog about tech."
keywords = []
images = []
# (Optional, default static/brand.svg) Set the path to a logo for the Geekblog
# relative to your 'static/' folder.
logo = "logo.png"
# (Optional, default 6) Set how many table of contents levels to be showed on page.
# Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
# You can also specify this parameter per page in front matter.
geekblogToC = 3
# (Optional, default none) Add a link to your Legal Notice page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogLegalNotice = "https://blog.example.com/legal"
# (Optional, default none) Add a link to your Privacy Policy page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogPrivacyPolicy = "/privacy"
# (Optional, default true) Add an anchor link to headlines.
geekblogAnchor = true
# (Optional, default true) Copy anchor url to clipboard on click.
geekblogAnchorCopy = true
# (Optional, default none) Sites main author.
geekblogAuthor = "john-doe"
# (Optional, default posts) Set the name of the default content section.
geekblogContentSection = "my-pages"
# (Optional, default true) Enable or disable image lazy loading for images rendered
# by the 'img' shortcode.
geekblogImageLazyLoading = true
# (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. It might be required
# if a subdirectory is used within Hugo's BaseURL.
# See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
geekblogOverwriteHTMLBase = false
# (Optional, default true) Enable or disable adding tags automatically to the main menu.
geekblogTagsToMenu = true
# (Optional, default none) Adds a "Hosted on <provider>" line to the footer.
# Could be used if you want to give credits to your hosting provider.
[params.geekblogHostedOn]
name = "Uberspace"
link = "https://uberspace.de/en/"
# (Optional, default none) Adds a "Content licensed under <license>" line to the footer.
# Could be used if you want to define a default license for your content.
[params.geekblogContentLicense]
name = "CC BY-SA 4.0"
link = "https://creativecommons.org/licenses/by-sa/4.0/"
```
{{< /tab >}}
{{< tab "YAML" >}}
```Yaml
---
# ...
theme: hugo-geekblog
paginate: 5
pluralizeListTitles: false
# Required to get well formatted code blocks
pygmentsUseClasses: true
pygmentsCodeFences: true
disablePathToLower: true
enableGitInfo: true
# Required if you want to render robots.txt template
enableRobotsTXT: true
markup:
goldmark:
renderer:
unsafe: true
tableOfContents:
startLevel: 1
endLevel: 9
taxonomies:
author: authors
tag: tags
mediaTypes:
"application/atom+xml":
suffixes:
- "xml"
outputFormats:
Atom:
# https://validator.w3.org/feed/docs/atom.html#whatIsAtom
name: "Atom"
mediaType: "application/atom+xml"
# generated file: <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
baseName: "feed"
isPlainText: false
rel: "alternate"
isHTML: false
noUgly: true
permalinkable: false
outputs:
home:
- HTML
- ATOM
page:
- HTML
section:
- HTML
taxonomy:
- HTML
term:
- HTML
- ATOM
params:
subtitle: "Blog about my favorite topics"
description: "This is my personal blog about tech."
keywords: []
images: []
# (Optional, default static/brand.svg) Set the path to a logo for the Geekblog
# relative to your 'static/' folder.
logo: logo.png
# (Optional, default 6) Set how many table of contents levels to be showed on page.
# Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
# You can also specify this parameter per page in front matter.
geekblogToC: 3
# (Optional, default none) Add a link to your Legal Notice page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogLegalNotice: https://blog.example.com/legal
# (Optional, default none) Add a link to your Privacy Policy page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogPrivacyPolicy: /privacy
# (Optional, default true) Add an anchor link to headlines.
geekblogAnchor: true
# (Optional, default true) Copy anchor url to clipboard on click.
geekblogAnchorCopy: true
# (Optional, default none) Sites main author.
geekblogAuthor: john-doe
# (Optional, default posts) Set the name of the default content section.
geekblogContentSection: "my-pages"
# (Optional, default true) Enable or disable image lazy loading for images rendered
# by the 'img' shortcode.
geekblogImageLazyLoading: true
# (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. It might be required
# if a subdirectory is used within Hugo's BaseURL.
# See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
geekblogOverwriteHTMLBase: false
# (Optional, default true) Enable or disable adding tags automatically to the main menu.
geekblogTagsToMenu: true
# (Optional, default none) Adds a "Hosted on <provider>" line to the footer.
# Could be used if you want to give credits to your hosting provider.
geekblogHostedOn:
name: Uberspace
link: https://uberspace.de/en/
# (Optional, default none) Adds a "Content licensed under <license>" line to the footer.
# Could be used if you want to define a default license for your content.
geekblogContentLicense:
name: CC BY-SA 4.0
link: https://creativecommons.org/licenses/by-sa/4.0/
```
{{< /tab >}}
{{< /tabs >}}
### Page configuration
{{< tabs "page-config" >}}
{{< tab "TOML" >}}
```Toml
# Title of your post. If not set, filename will be used.
title = My first post
# Set weigth to 1 to mark this post as sticky post.
weight = 1
# List of authors of the post.
authors = ["john-doe"]
# Tags for this post.
tags = ["Open Source"]
# Set how many table of contents levels to be showed on page.
geekblogToC = 3
# Set true to hide page or section from side menu (file-tree menu only).
geekblogHidden = true
# Add an anchor link to headlines.
geekblogAnchor = true
```
{{< /tab >}}
{{< tab "YAML" >}}
```Yaml
# Title of your post. If not set, filename will be used.
title: My first post
# Set weigth to 1 to mark this post as sticky post.
weight: 1
# List of authors of the post.
authors:
- john-doe
# Tags for this post.
tags:
- Open Source
# Set how many table of contents levels to be showed on page.
geekblogToC: 3
# Set true to hide page or section from side menu (file-tree menu only).
geekblogHidden: true
# Add an anchor link to headlines.
geekblogAnchor: true
```
{{< /tab >}}
{{< /tabs >}}
## Menus
### Extra menu
If you want to customize the menus (header and footer), this can be achieved by a data file. This file needs to be written in YAML and placed at data/menu/extra.yml.
**Example:**
```Yaml
---
header:
- name: Github Profile
icon: gblog_github
ref: "https://github.com/xoxys"
external: true
footer:
- name: Contact
icon: gblog_email
ref: "/contact"
```
## Custom icons
The only supported source for custom icons are SVG sprites. Some icon frameworks provides ready to use sprites e.g. FontAwesome. If the framework don't provide sprites, you can create your own from raw SVG icons. There are a lot of tools available to create sprites, please choose one that fits your need. One solution could be [svgsprit.es](https://svgsprit.es/).
Regardless of which tool (or existing sprite) you choose, there are a few requirements that must be met:
1. The sprite must be a valid **SVG** file.
2. You have to ensure to **hide the sprite**. Apply the predefined class `svg-sprite` or `hidden` to the root element of your sprite or add a small piece of inline CSS e.g. `style="display: none;"`.
3. Save the sprite to the folder `assets/sprites` right beside your `content` folder.
The result of a valid minimal SVG sprite file could look like this:
```XML
<svg class="svg-sprite" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<symbol viewBox="-2.29 -2.29 28.57 28.57" id="arrow_back" xmlns="http://www.w3.org/2000/svg">
<path d="M24 10.526v2.947H5.755l8.351 8.421-2.105 2.105-12-12 12-12 2.105 2.105-8.351 8.421H24z"/>
</symbol>
</svg>
```
**Example:**
FontAwesome provides three pre-build sprites included in the regular Web download pack, `sprites/brands.svg`, `sprites/regular.svg` and `sprites/solid.svg`. Choose your sprite to use and copy it to your projects root directory into `assets/sprites`, right beside your `content` folder. The result should look like this:
```Bash
my_projcet/
├── assets
│ └── sprites
│ └── regular.svg
├── config.yaml
├── content
│ ├── _index.md
│ ├── ...
```
That's it! The theme will auto-load all available SVG sprites provided in the assets folder. To use the icons, you need to lookup the id of the icon. An example would be `thumbs-up` {{< icon "thumbs-up" >}}. There is also a [shortcode](/posts/shortcodes/#icon) available
## Build-in icons
The theme bundles just a small set of hand crafted icons.
{{< sprites >}}
## Setup Authors
The theme supports multiple authors. The required information for each author need to be stored in a single [Hugo data template](https://gohugo.io/templates/data-templates/) per author. These files need to be stored in the `data/authors/` directory in your projects root:
```Shell
data/
└── authors
├── john-doe.yml
├── richard-roe.yml
└── Special User.yml
```
The name of the file will be used as the reference later, so if you prefer some kind of naming convention this need to covered by the file names. Example authors file:
```YAML
name: John Doe
email: john@example.com
```
With the defined files, you can add as many authors as you want to the front matter of your posts:
```Markdown
---
title: Demo Posts
authors:
- john-doe
- Special User
---
My first demo post.
```
## Known Limitations
### Minify HTML results in spacing issues
Using `hugo --minify` without further configuration or using other minify tools that also minify HTML files might result in spacing issues in the theme and is **not** supported.
After some testing we decided to not spend effort to fix this issue for now as the benefit is very low. There are some parts of the theme where spaces between HTML elements matters but were stripped by minify tools. Some of these issues are related to <!-- spellchecker-disable -->[gohugoio/hugo#6892](https://github.com/gohugoio/hugo/issues/6892).<!-- spellchecker-enable --> While recommendation like "don't depend on whitespace in your layout" sounds reasonable, it seems to be not that straight forward especially for something like embedded icons into the text flow.
If you still want to use Hugo's minify flag you should at least exclude HTML file in your site [configuration](https://gohugo.io/getting-started/configuration/#configure-minify):
```toml
[minify]
disableHTML = true
```

5
exampleSite/content/posts/markdown.md
View File

@ -5,6 +5,7 @@ authors:
- john-doe - john-doe
tags: tags:
- Documentation - Documentation
weight: 10
--- ---
This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme. This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.
@ -117,10 +118,9 @@ Tables aren't part of the core Markdown spec, but Hugo supports supports them ou
#### Code block with Hugo's internal highlight Shortcode #### Code block with Hugo's internal highlight Shortcode
<!-- prettier-ignore-start -->
<!-- markdownlint-disable --> <!-- markdownlint-disable -->
<!-- spellchecker-disable --> <!-- spellchecker-disable -->
<!-- prettier-ignore -->
{{< highlight html "linenos=table" >}} {{< highlight html "linenos=table" >}}
<!doctype html> <!doctype html>
@ -136,7 +136,6 @@ Tables aren't part of the core Markdown spec, but Hugo supports supports them ou
{{< /highlight >}} {{< /highlight >}}
<!-- spellchecker-enable --> <!-- spellchecker-enable -->
<!-- markdownlint-restore --> <!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
## List Types ## List Types

1
exampleSite/content/posts/post-short.md
View File

@ -5,6 +5,7 @@ authors:
- john-doe - john-doe
tags: tags:
- Development - Development
weight: 10
--- ---
Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious copious quo ad. Stet probates in duo. Dolor sit, sumo unique argument um no. Gracie nominal id xiv. Romanesque acclimates investiture. Ornateness bland it ex enc, est yeti am bongo detract re. Pro ad prompts feud gait, quid exercise emeritus bis e. In pro quints consequent, denim fastidious copious quo ad. Stet probates in duo.

3
exampleSite/content/posts/post-with-images/index.md
View File

@ -6,7 +6,6 @@ authors:
tags: tags:
- Documentation - Documentation
- Shortcodes - Shortcodes
weight: 20
resources: resources:
- name: feature - name: feature
src: "images/feature.jpg" src: "images/feature.jpg"
@ -52,6 +51,8 @@ resources:
If you need more flexibility for your embedded images, you could use the `img` shortcode. It is using Hugo's If you need more flexibility for your embedded images, you could use the `img` shortcode. It is using Hugo's
[page resources](https://gohugo.io/content-management/page-resources/) and supports lazy loading of your images. [page resources](https://gohugo.io/content-management/page-resources/) and supports lazy loading of your images.
<!--more-->
**Attributes:** **Attributes:**
| Name | Usage | default | | Name | Usage | default |

11
exampleSite/content/posts/sticky.md
View File

@ -1,11 +0,0 @@
---
title: Simple sticky posts
weight: 1
date: 2020-06-13T00:06:00+02:00
authors:
- john-doe
tags:
- Open Source
---
Sticky (or pinned) posts implementation is currently really simple and handled by `weight: 1` in a post front matter.

315
exampleSite/content/posts/usage/configuration.md Normal file
View File

@ -0,0 +1,315 @@
---
title: Configuration
date: 2021-05-23T20:00:00+01:00
authors:
- john-doe
tags:
- Documentation
- Usage
---
Overview of all available site and page configuration options provided by the theme.
<!--more-->
{{< toc >}}
## Configuration
### Site configuration
{{< tabs "site-config" >}}
{{< tab "TOML" >}}
```Toml
baseURL = "http://localhost"
title = "Geekblog"
theme = "hugo-geekblog"
paginate = 5
pluralizeListTitles = false
# Required to get well formatted code blocks
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
enableGitInfo = true
# Required if you want to render robots.txt template
enableRobotsTXT = true
[markup]
[markup.goldmark.renderer]
unsafe = true
[markup.tableOfContents]
startLevel = 1
endLevel = 9
[taxonomies]
author = "authors"
tag = "tags"
[mediaTypes]
[mediaTypes."application/atom+xml"]
suffixes = ["xml"]
[outputFormats]
[outputFormats.Atom]
# https://validator.w3.org/feed/docs/atom.html#whatIsAtom
name = "Atom"
mediaType = "application/atom+xml"
# generated file = <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
baseName = "feed"
isPlainText = false
rel = "alternate"
isHTML = false
noUgly = true
permalinkable = false
[outputs]
home = ["HTML", "ATOM"]
page = ["HTML"]
section = ["HTML"]
taxonomy = ["HTML"]
term = ["HTML", "ATOM"]
[params]
subtitle = "Blog about my favorite topics"
description = "This is my personal blog about tech."
keywords = []
images = []
# (Optional, default static/brand.svg) Set the path to a logo for the Geekblog
# relative to your 'static/' folder.
logo = "logo.png"
# (Optional, default 6) Set how many table of contents levels to be showed on page.
# Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
# You can also specify this parameter per page in front matter.
geekblogToC = 3
# (Optional, default none) Add a link to your Legal Notice page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogLegalNotice = "https://blog.example.com/legal"
# (Optional, default none) Add a link to your Privacy Policy page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogPrivacyPolicy = "/privacy"
# (Optional, default true) Add an anchor link to headlines.
geekblogAnchor = true
# (Optional, default true) Copy anchor url to clipboard on click.
geekblogAnchorCopy = true
# (Optional, default none) Sites main author.
geekblogAuthor = "john-doe"
# (Optional, default posts) Set the name of the default content section.
geekblogContentSection = "my-pages"
# (Optional, default true) Enable or disable image lazy loading for images rendered
# by the 'img' shortcode.
geekblogImageLazyLoading = true
# (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. It might be required
# if a subdirectory is used within Hugo's BaseURL.
# See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
geekblogOverwriteHTMLBase = false
# (Optional, default true) Enable or disable adding tags automatically to the main menu.
geekblogTagsToMenu = true
# (Optional, default none) Adds a "Hosted on <provider>" line to the footer.
# Could be used if you want to give credits to your hosting provider.
[params.geekblogHostedOn]
name = "Uberspace"
link = "https://uberspace.de/en/"
# (Optional, default none) Adds a "Content licensed under <license>" line to the footer.
# Could be used if you want to define a default license for your content.
[params.geekblogContentLicense]
name = "CC BY-SA 4.0"
link = "https://creativecommons.org/licenses/by-sa/4.0/"
```
{{< /tab >}}
{{< tab "YAML" >}}
```Yaml
---
# ...
theme: hugo-geekblog
paginate: 5
pluralizeListTitles: false
# Required to get well formatted code blocks
pygmentsUseClasses: true
pygmentsCodeFences: true
disablePathToLower: true
enableGitInfo: true
# Required if you want to render robots.txt template
enableRobotsTXT: true
markup:
goldmark:
renderer:
unsafe: true
tableOfContents:
startLevel: 1
endLevel: 9
taxonomies:
author: authors
tag: tags
mediaTypes:
"application/atom+xml":
suffixes:
- "xml"
outputFormats:
Atom:
# https://validator.w3.org/feed/docs/atom.html#whatIsAtom
name: "Atom"
mediaType: "application/atom+xml"
# generated file: <baseName>.<mediaType."application/atom+xml".suffixes[0]> = atom.xml
baseName: "feed"
isPlainText: false
rel: "alternate"
isHTML: false
noUgly: true
permalinkable: false
outputs:
home:
- HTML
- ATOM
page:
- HTML
section:
- HTML
taxonomy:
- HTML
term:
- HTML
- ATOM
params:
subtitle: "Blog about my favorite topics"
description: "This is my personal blog about tech."
keywords: []
images: []
# (Optional, default static/brand.svg) Set the path to a logo for the Geekblog
# relative to your 'static/' folder.
logo: logo.png
# (Optional, default 6) Set how many table of contents levels to be showed on page.
# Use false to hide ToC, note that 0 will default to 6 (https://gohugo.io/functions/default/)
# You can also specify this parameter per page in front matter.
geekblogToC: 3
# (Optional, default none) Add a link to your Legal Notice page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogLegalNotice: https://blog.example.com/legal
# (Optional, default none) Add a link to your Privacy Policy page to the site footer.
# It can be either a remote url or a local file path relative to your content directory.
geekblogPrivacyPolicy: /privacy
# (Optional, default true) Add an anchor link to headlines.
geekblogAnchor: true
# (Optional, default true) Copy anchor url to clipboard on click.
geekblogAnchorCopy: true
# (Optional, default none) Sites main author.
geekblogAuthor: john-doe
# (Optional, default posts) Set the name of the default content section.
geekblogContentSection: "my-pages"
# (Optional, default true) Enable or disable image lazy loading for images rendered
# by the 'img' shortcode.
geekblogImageLazyLoading: true
# (Optional, default false) Set HTMl <base> to .Site.BaseURL if enabled. It might be required
# if a subdirectory is used within Hugo's BaseURL.
# See https://developer.mozilla.org/de/docs/Web/HTML/Element/base.
geekblogOverwriteHTMLBase: false
# (Optional, default true) Enable or disable adding tags automatically to the main menu.
geekblogTagsToMenu: true
# (Optional, default none) Adds a "Hosted on <provider>" line to the footer.
# Could be used if you want to give credits to your hosting provider.
geekblogHostedOn:
name: Uberspace
link: https://uberspace.de/en/
# (Optional, default none) Adds a "Content licensed under <license>" line to the footer.
# Could be used if you want to define a default license for your content.
geekblogContentLicense:
name: CC BY-SA 4.0
link: https://creativecommons.org/licenses/by-sa/4.0/
```
{{< /tab >}}
{{< /tabs >}}
### Page configuration
{{< tabs "page-config" >}}
{{< tab "TOML" >}}
```Toml
# Title of your post. If not set, filename will be used.
title = My first post
# Set weigth to 1 to mark this post as sticky post.
weight = 1
# List of authors of the post.
authors = ["john-doe"]
# Tags for this post.
tags = ["Open Source"]
# Set how many table of contents levels to be showed on page.
geekblogToC = 3
# Add an anchor link to headlines.
geekblogAnchor = true
```
{{< /tab >}}
{{< tab "YAML" >}}
```Yaml
# Title of your post. If not set, filename will be used.
title: My first post
# Set weigth to 1 to mark this post as sticky post.
weight: 1
# List of authors of the post.
authors:
- john-doe
# Tags for this post.
tags:
- Open Source
# Set how many table of contents levels to be showed on page.
geekblogToC: 3
# Add an anchor link to headlines.
geekblogAnchor: true
```
{{< /tab >}}
{{< /tabs >}}

258
exampleSite/content/posts/usage/getting-started.md Normal file
View File

@ -0,0 +1,258 @@
---
title: Getting Started
date: 2020-07-15T20:00:00+02:00
authors:
- john-doe
- Special User
tags:
- Documentation
- Usage
weight: 1
---
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 of complex projects. If a more feature-complete theme is required there are a lot of got alternatives out there. This post helps you to get started with the Geekblog theme, including initial setup and basic configuration.
<!--more-->
[![Build Status](https://img.shields.io/drone/build/thegeeklab/hugo-geekblog?logo=drone&server=https%3A%2F%2Fdrone.thegeeklab.de)](https://drone.thegeeklab.de/thegeeklab/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/thegeeklab/hugo-geekblog)](https://github.com/thegeeklab/hugo-geekblog/releases/latest)
[![GitHub contributors](https://img.shields.io/github/contributors/thegeeklab/hugo-geekblog)](https://github.com/thegeeklab/hugo-geekblog/graphs/contributors)
[![License: MIT](https://img.shields.io/github/license/thegeeklab/hugo-geekblog)](https://github.com/thegeeklab/hugo-geekblog/blob/main/LICENSE)
{{< toc >}}
## Features
- Clean and simple design
- Light and mobile-friendly
- Easy customization
- Zero initial configuration
- Handy shortcodes
- Simple sticky posts
- Content tags
- Multiple authors
- Supports Atom and JSON feeds
## Setup 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
npx 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-bundle) (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](#configuration).
```Toml
baseURL = "http://localhost"
title = "Geekblog"
theme = "hugo-geekblog"
pluralizeListTitles = false
# Geekblog required configuration
pygmentsUseClasses = true
pygmentsCodeFences = true
disablePathToLower = true
# Needed for mermaid shortcodes
[markup]
[markup.goldmark.renderer]
unsafe = true
[markup.tableOfContents]
startLevel = 1
endLevel = 9
[taxonomies]
author = "authors"
tag = "tags"
[mediaTypes]
[mediaTypes."application/atom+xml"]
suffixes = ["xml"]
[outputFormats]
[outputFormats.Atom]
name = "Atom"
mediaType = "application/atom+xml"
baseName = "feed"
isPlainText = false
rel = "alternate"
isHTML = false
noUgly = true
permalinkable = false
[outputs]
home = ["HTML", "ATOM"]
page = ["HTML"]
section = ["HTML"]
taxonomy = ["HTML"]
term = ["HTML", "ATOM"]
```
5. Test your site.
```Shell
hugo server -D
```
If you want to add some demo data you could use the content from the [Hugo basic example](https://github.com/gohugoio/hugoBasicExample):
```Shell
curl -L https://github.com/gohugoio/hugoBasicExample/archive/main.tar.gz | tar -xz --exclude "config*" --exclude "LICENSE" --exclude "README*" --strip-components=1
```
### Option 1: Download pre-build release bundle
Download and extract the latest release bundle into the theme directory.
```Shell
mkdir -p themes/hugo-geekblog/
curl -L https://github.com/thegeeklab/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/thegeeklab/hugo-geekblog.git themes/geekblog
```
Build required theme assets e.g. CSS files and SVG sprites with `gulp`.
```Shell
npx gulp default
```
## Deployments
### Netlify
There are several ways to deploy your site with this theme on Netlify. Regardless of which solution you choose, the main goal is to ensure that the prebuilt theme release tarball is used or to run the [required commands](#option-2-clone-the-github-repository) to prepare the theme assets before running the Hugo build command.
Here are some possible solutions:
**Use a Makefile:**
Add a Makefile to your repository to bundle the required steps.
```Makefile
THEME_VERSION := v0.8.2
THEME := hugo-geekblog
BASEDIR := docs
THEMEDIR := $(BASEDIR)/themes
.PHONY: doc
doc: doc-assets doc-build
.PHONY: doc-assets
doc-assets:
mkdir -p $(THEMEDIR)/$(THEME)/ ; \
curl -sSL "https://github.com/thegeeklab/$(THEME)/releases/download/${THEME_VERSION}/$(THEME).tar.gz" | tar -xz -C $(THEMEDIR)/$(THEME)/ --strip-components=1
.PHONY: doc-build
doc-build:
cd $(BASEDIR); hugo
.PHONY: clean
clean:
rm -rf $(THEMEDIR) && \
rm -rf $(BASEDIR)/public
```
This Makefile can be used in your `netlify.toml`, take a look at the Netlify [example](https://docs.netlify.com/configure-builds/file-based-configuration/#sample-file) for more information:
```toml
[build]
publish = "docs/public"
command = "make doc"
```
**Chain required commands:**
Chain all required commands to prepare the theme and build your site on the `command` option in your `netlify.toml` like this:
```toml
[build]
publish = "docs/public"
command = "command1 && command 2 && command3 && hugo"
```
### Subdirectories
{{< hint danger >}}
**Warning**\
As deploying Hugo sites on subdirectories is not as robust as on subdomains, we do not recommend this.
If you have a choice, using a domain/subdomain should always be the preferred solution!
{{< /hint >}}
If you want to deploy your side to a subdirectory of your domain, some extra steps are required:
- Configure your Hugo base URL e.g. `baseURL = http://localhost/demo/`.
- Don't use `relativeURLs: false` nor `canonifyURLs: true` as is can cause unwanted side effects!
There are two ways to get Markdown links or images working:
- Use the absolute path including your subdirectory e.g. `[testlink](/demo/example-site)`
- Overwrite the HTML base in your site configuration with `geekblogOverwriteHTMLBase = true` and use the relative path e.g. `[testlink](example-site)`
But there is another special case if you use `geekblogOverwriteHTMLBase = true`. If you use anchors in your Markdown links you have to ensure to always include the page path. As an example `[testlink](#some-anchor)` will resolve to `http://localhost/demo/#some-anchor` and not automatically include the current page!
## Known Limitations
### Minify HTML results in spacing issues
Using `hugo --minify` without further configuration or using other minify tools that also minify HTML files might result in spacing issues in the theme and is **not** supported.
After some testing we decided to not spend effort to fix this issue for now as the benefit is very low. There are some parts of the theme where spaces between HTML elements matters but were stripped by minify tools. Some of these issues are related to <!-- spellchecker-disable -->[gohugoio/hugo#6892](https://github.com/gohugoio/hugo/issues/6892).<!-- spellchecker-enable --> While recommendation like "don't depend on whitespace in your layout" sounds reasonable, it seems to be not that straight forward especially for something like embedded icons into the text flow.
If you still want to use Hugo's minify flag you should at least exclude HTML file in your site [configuration](https://gohugo.io/getting-started/configuration/#configure-minify):
```toml
[minify]
disableHTML = true
```
## Whats next?
There are a lot more things to discover. To get the most out of the Theme we have collected interesting posts covering more advanced topics:
- [Configuration](/posts/usage/configuration/)
- [Menus](/posts/usage/menus/)
- **Features**
- [Icon Sets](/posts/features/icon-sets/)
- [Authors](/posts/features/authors/)
- [Sticky Posts](/posts/features/sticky/)
- [Shortcodes](/posts/advanced/shortcodes/)
- [Table of Content](/posts/advanced/toc/)
- [Mermaid](/posts/advanced/mermaid/)
- [Advanced Images](/posts/post-with-images/)

33
exampleSite/content/posts/usage/menus.md Normal file
View File

@ -0,0 +1,33 @@
---
title: Menus
date: 2021-05-23T20:00:00+01:00
authors:
- john-doe
tags:
- Documentation
- Usage
---
The theme supports different kinds of menus.
<!--more-->
### Extra menu
If you want to customize the menus (header and footer), this can be achieved by a data file. This file needs to be written in YAML and placed at data/menu/extra.yml.
**Example:**
```Yaml
---
header:
- name: Github Profile
icon: gblog_github
ref: "https://github.com/xoxys"
external: true
footer:
- name: Contact
icon: gblog_email
ref: "/contact"
```