code cleanup and add documentation for config params

This commit is contained in:
Robert Kaussow 2020-01-14 00:15:39 +01:00
parent f2f51adff0
commit aac46df166
12 changed files with 196 additions and 43 deletions

View file

@ -1,6 +1,8 @@
# Hugo Geekdoc Theme
[![Build Status](https://cloud.drone.io/api/badges/xoxys/hugo-geekdoc/status.svg)](https://cloud.drone.io/xoxys/hugo-geekdoc)
[![Hugo](https://img.shields.io/badge/hugo-0.55-blue.svg)](https://gohugo.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![GitHub All Releases](https://img.shields.io/github/downloads/xoxys/hugo-geekdoc/total)
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.

View file

@ -19,37 +19,10 @@ markup:
startLevel: 1
params:
# (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
GeekdocToC: 3
geekdocToC: 3
# (Optional, default none) Set the path to a logo for the Geekdoc. If the logo is
# /static/logo.png then the path would be logo.png
# GeekdocLogo: /logo.png
geekdocRepo: https://github.com/xoxys/hugo-geekdoc
geekdocEditPath: edit/master/exampleSite/content
# (Optional, default none) Set leaf bundle to render as side menu
# When not specified file structure and weights will be used
# GeekdocMenuBundle: /menu
# (Optional, default docs) Specify section of content to render as menu
# You can also set value to '*' to render all sections to menu
GeekdocSection: docs
# Set source repository location.
# Used for 'Last Modified' and 'Edit this page' links.
GeekdocRepo: https://github.com/xoxys/hugo-geekdoc
# Enable "Edit this page" links for 'doc' page type.
# Disabled by default. Uncomment to enable. Requires 'GeekdocRepo' param.
# Path must point to 'content' directory of repo.
GeekdocEditPath: edit/master/exampleSite/content
# Configure the date format used on the pages
# - In git information
# - In blog posts
GeekdocDateFormat: "Jan 2, 2006"
# (Optional, default true) Enables search function with flexsearch,
# Index is built on fly, therefore it might slowdown your website.
GeekdocSearch: true
geekdocDateFormat: "Jan 2, 2006"
geekdocSearch: true

View file

@ -2,6 +2,5 @@
title: News
type: posts
weight: 10
listonly: true
geekdocHidden: true
---

View file

@ -0,0 +1,164 @@
## Site configuration
{{< tabs "site-config" >}}
{{< tab "TOML" >}}
```Toml
[params]
# (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.
geekdocToC = 3
# (Optional, default static/brand.svg) Set the path to a logo for the Geekdoc
# relative to your 'static/' folder.
geekdocLogo = logo.png
# (Optional, default false) Render menu from data file im 'data/menu/main.yaml'.
geekdocMenuBundle = true
# (Optional, default true) Show page navigation links at the bottom of each
# docs page (bundle menu only).
geekdocNextPrev = false
# (Optional, default true) Show a breadcrumb navigation bar at the top of each docs page.
# You can also specify this parameter per page in front matter.
geekdocBreadcrumb = false
# (Optional, default none) Set source repository location
# Used for 'Edit this page' links
# You can also specify this parameter per page in front matter.
geekdocRepo = 'https://github.com/xoxys/hugo'
# (Optional, default none) Enable "Edit this page" links. Requires 'GeekdocRepo' param
# and path must point to 'content' directory of repo.
# You can also specify this parameter per page in front matter.
geekdocEditPath = 'edit/master/exampleSite/content'
# (Optional, default 'Jan 2, 2006') Configure the date format used on the pages in blog posts.
geekdocDateFormat = "Jan 2, 2006"
# (Optional, default true) Enables search function with flexsearch.
# Index is built on the fly and might slowdown your website.
geekdocSearch = false
```
{{< /tab >}}
{{< tab "YAML" >}}
```Yaml
params:
# (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.
geekdocToC: 3
# (Optional, default static/brand.svg) Set the path to a logo for the Geekdoc
# relative to your 'static/' folder.
geekdocLogo: logo.png
# (Optional, default false) Render menu from data file im 'data/menu/main.yaml'.
# See also https://docs.geeklabor.de/usage/menus/#bundle-menu
geekdocMenuBundle: true
# (Optional, default true) Show page navigation links at the bottom of each
# docs page (bundle menu only).
geekdocNextPrev: false
# (Optional, default true) Show a breadcrumb navigation bar at the top of each docs page.
# You can also specify this parameter per page in front matter.
geekdocBreadcrumb: false
# (Optional, default none) Set source repository location
# Used for 'Edit this page' links
# You can also specify this parameter per page in front matter.
geekdocRepo: https://github.com/xoxys/hugo-geekdoc
# (Optional, default none) Enable "Edit this page" links. Requires 'GeekdocRepo' param
# and path must point to 'content' directory of repo.
# You can also specify this parameter per page in front matter.
geekdocEditPath: edit/master/exampleSite/content
# (Optional, default 'Jan 2, 2006') Configure the date format used on the pages in blog posts.
geekdocDateFormat: "Jan 2, 2006"
# (Optional, default true) Enables search function with flexsearch.
# Index is built on the fly and might slowdown your website.
geekdocSearch: false
```
{{< /tab >}}
{{< /tabs >}}
## Page configuration
{{< tabs "page-config" >}}
{{< tab "TOML" >}}
```Toml
# Set type to 'posts' if you want to render page as blogpost
type = 'posts'
# Set page weight to re-arrange items in file-tree menu
weight = 10
# Set how many table of contents levels to be showed on page.
geekdocToC = 3
# Show a breadcrumb navigation bar at the top of each docs page.
geekdocBreadcrumb = false
# Set source repository location
geekdocRepo = 'https://github.com/xoxys/hugo-geekdoc'
# Enable "Edit this page" links. Requires 'GeekdocRepo' param and path must point
# to 'content' directory of repo.
geekdocEditPath = 'edit/master/exampleSite/content'
# Used for 'Edit this page' link, set to '.File.Path' by default.
# Can be overwritten by a path relative to 'geekdocEditPath'
geekdocFilePath =
# Set to mark page as flat section (file-tree menu only)
geekdocFlatSection = true
# Set true to hide page or section from side menu (file-tree menu only)
geekdocHidden = true
```
{{< /tab >}}
{{< tab "YAML" >}}
```Yaml
# Set type to 'posts' if you want to render page as blogpost
type: 'posts'
# Set page weight to re-arrange items in file-tree menu
weight: 10
# Set how many table of contents levels to be showed on page.
geekdocToC: 3
# Show a breadcrumb navigation bar at the top of each docs page.
geekdocBreadcrumb: false
# Set source repository location
geekdocRepo: https://github.com/xoxys/hugo-geekdoc
# Enable "Edit this page" links. Requires 'GeekdocRepo' param and path must point
# to 'content' directory of repo.
geekdocEditPath: edit/master/exampleSite/content
# Used for 'Edit this page' link, set to '.File.Path' by default.
# Can be overwritten by a path relative to 'geekdocEditPath'
geekdocFilePath =
# Set to mark page as flat section (file-tree menu only)
geekdocFlatSection: true
# Set true to hide page or section from side menu (file-tree menu only)
geekdocHidden: true
```
{{< /tab >}}
{{< /tabs >}}

View file

@ -1 +1,3 @@
...
## File-tree menu
## Bundle menu

View file

@ -0,0 +1,13 @@
---
more:
- name: News
ref: "/posts"
icon: "notification"
- name: Releases
ref: "https://github.com/xoxys/hugo-geekdoc/releases"
external: true
icon: "download"
- name: "View Source"
ref: "https://github.com/xoxys/hugo-geekdoc"
external: true
icon: "github"

BIN
exampleSite/static/logo.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 127 KiB

View file

@ -8,9 +8,9 @@
<ul class="gdoc-nav__list">
{{ range .sect.GroupBy "Weight" "desc" }}
{{ range .ByTitle }}
{{ if not .Params.geekdocHidden }}
<li>
{{ if or .Content .Params.ListOnly }}
{{ if or .Content .Params.geekdocFlatSection }}
<span class="flex">
<a href="{{ .RelPermalink }}" class="gdoc-nav__entry {{ if eq $current . }}is-active{{ end }}">
{{ partial "title" . }}
@ -21,11 +21,11 @@
{{ end }}
{{ $numberOfPages := (add (len .Pages) (len .Sections)) }}
{{ if and (ne $numberOfPages 0) (not .Params.ListOnly) }}
{{ if and (ne $numberOfPages 0) (not .Params.geekdocFlatSection) }}
{{ template "tree-nav" dict "sect" .Pages "current" $current}}
{{ end }}
</li>
{{ end }}
{{ end }}
{{ end }}
</ul>

View file

@ -44,7 +44,7 @@
<div class="gdoc-page__footer flex justify-between">
{{ $showPrevNext := (and (not .Params.disableNextPrev) (not .Site.Params.disableNextPrev) .Site.Params.GeekdocMenuBundle) }}
{{ $showPrevNext := (and (not .Site.Params.GeekdocNextPrev) .Site.Params.GeekdocMenuBundle) }}
{{ if $showPrevNext }}
<span>
{{ with ($current.Scratch.Get "prevPage") }}

View file

@ -17,7 +17,7 @@
{{end}}
<div class="gdoc-page__header flex justify-between" itemscope itemtype="http://data-vocabulary.org/Breadcrumb">
{{$showBreadcrumb := (and (not .Params.disableBreadcrumb) (not .Site.Params.disableBreadcrumb))}}
{{$showBreadcrumb := (and (not .Page.Params.geekdocBreadcrumb) (not .Site.Params.geekdocBreadcrumb))}}
<span>
{{if $showBreadcrumb}}
<span class="breadcrumb">

View file

@ -6,7 +6,7 @@
</label>
<a class="gdoc-header__link" href="{{ .Site.BaseURL }}">
<span class="gdoc-brand flex align-center">
<img class="gdoc-brand__img" src="{{ "brand.svg" | relURL }}" alt="Branding" width=48 height=48>
<img class="gdoc-brand__img" src="{{ (default "brand.svg" .Site.Params.GeekdocLogo) | relURL }}" alt="{{ .Site.Title }}" width=38 height=38>
{{ .Site.Title }}
</span>
</a>

View file

@ -102,7 +102,7 @@ img {
font-size: $font-size-16 * 2;
&__img {
padding: 0 $padding-16 0 0;
margin-right: $padding-16;
}
}