code cleanup and add documentation for config params

README.md

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

exampleSite/config.yaml

@@ -19,37 +19,10 @@ markup:
     startLevel: 1
 
 params:
-  # (Optional, default 6) Set how many table of contents levels to be showed on page.
+  geekdocToC: 3
-  # 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 none) Set the path to a logo for the Geekdoc. If the logo is
+  geekdocRepo: https://github.com/xoxys/hugo-geekdoc
-  # /static/logo.png then the path would be logo.png
+  geekdocEditPath: edit/master/exampleSite/content
-  # GeekdocLogo: /logo.png
 
-  # (Optional, default none) Set leaf bundle to render as side menu
+  geekdocDateFormat: "Jan 2, 2006"
-  # When not specified file structure and weights will be used
+  geekdocSearch: true
-  # 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

exampleSite/content/posts/_index.md

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

exampleSite/content/usage/configuration.md

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

exampleSite/content/usage/menus.md

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

exampleSite/data/menu/more.yaml

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

layouts/partials/menu-filetree.html

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

layouts/partials/page-footer.html

@@ -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") }}

layouts/partials/page-header.html

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

layouts/partials/site-header.html

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

src/sass/_base.scss

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