{{- if .Site.Params.menutopbar.googleTranslateEnable }}
{{- if or (not .IsHome) .Site.Params.menutopbar.googleTranslateShowOnHome }}
{{ partial "header.nav.google.translate.html" . -}}
{{- end }}
{{- end }}
```
#### No translation is done for
* About and Adress in footer (class="notranslate")
`layouts/partials/footer.html`
```
{{ default "About" (i18n "aboutUs") }}
{{- .Site.Params.aboutUs | markdownify }}
```
* results of shortcode highlight (internal), w3-code, w3-codespan, cscb and csc
* currently results of markdown backticks get translated, which is odd
### Google Custom Search API
```toml
# https://cse.google.com/cse/
# used in layouts/partials/search.google.gcse.html
googleCustomSearchCX = '002931815551392744433:tnypjyusk2e'
```
* Used for search page /search which is linked into the toolbar menu here:
```toml
[[menu.topbar]]
weight = 5
name = "Search"
url = "/search"
pre = "fas fa-search"
```
* Google does not index github pages (?).
Search on exampleSite: https://it-gro.github.io/hugo-theme-w3css-basic.github.io/search/
is "empty" :-(
* Search form
* Search form with disabled Javascript
### Google Analytics-Tracking using gtag
* The Global Site Tag (gtag.js) is the new version of Google Analytics JavaScript capture API.
* This theme uses the new gtags.js (not the old google analytics.js)
* [Analytics-Tracking using gtag.js](https://support.google.com/analytics/answer/1008080)
* [gtag.js Developer Guide](https://developers.google.com/gtagjs/)
```toml
# Enable Google Analytics by entering your tracking code
googleAnalytics = ""
[params]
# https://developers.google.com/gtagjs/
# used in layouts/partials/head.google.gtags.html
# you need to enter the Tracking-ID above
enableGoogleGtag=true
```
* Firefox has a [Tracking Protection](https://support.mozilla.org/en-US/kb/tracking-protection) which
prevents `gtag.js` tracking by default.
* `gtag.js` is not used if `enableGoogleGtag` is not set to `true` or the tracking code is not given (`googleAnalytics`)
```
{{- if and $.Site.Params.enableGooglesGtag $.Site.GoogleAnalytics }}
{{- /* */}}
```
### Footer
```toml
# used in layouts/partials/footer.html
# uses markdownify
aboutUs = '''
....
'''
address = '''
....
'''
# used in layouts/partials/footer.bottom.html
bottomLeft = "Copyright (c) 2018, *lobortis nisl* ut aliquip ex ea commodo consequat"
bottomRight = 'created with [Hugo](https://gohugo.io) '
```
### cookieconsent
* https://cookieconsent.insites.com
```
static/vendor/insites/
└── cookieconsent
├── cookieconsent.3.0.6.min.css
└── cookieconsent.3.0.6.min.js
```
`i18n/en.yaml`
```
# Cookie consent
- id: cookieMessage
translation: This website uses cookies to ensure you get the best experience on our website.
- id: cookieDismiss
translation: Got it!
- id: cookieLearn
translation: Learn more
```
`config.toml`
```toml
[params.cookieconsent]
# https://cookieconsent.insites.com/download/
# used in layouts/partials/head.cookieconsent.html
enable = true
popupBackground = "#efefef"
popupText = "#404040"
buttonBackground = "#8ec760"
buttonText = "#ffffff"
#static = "true"
position = "bottom"
#position = "top"
#position = "bottom-left"
#position = "bottom-right"
#position = "top-left"
#position = "top-right"
theme = "classic"
#theme = "edgeless"
#theme = ""
href = "https://cookiesandyou.com"
```
### RSS
* This theme uses the Hugo's embedded rss.xml https://gohugo.io/templates/rss/#the-embedded-rss-xml
* Default configuration is explained here:
* https://gohugo.io/templates/rss/#configure-rss
* https://gohugo.io/getting-started/configuration/#toml-configuration
```toml
# RSS Feed
# Do not build RSS files
disableRSS = false
# maximum number of items in the RSS feed
rssLimit = 10
```
### Tracing
* If you like comments in the html source, this one is for you
```toml
# flags used for tracing and html comment output
# currently used:
# html-comment enable partials html comment output
# debug-shortcodes enable all shortcodes debugging output
# debug-shortcode-liti enable all shortcode liti debugging output
# traceFlags = "html-comment:debug-shortcode-liti"
traceFlags = "html-comment"
```
If `traceFlags` includes the word `html-comment` some HTML comments will
be included in the html source code.
## Custom CSS and JS
* This theme comes with the following "empty" files
```
static/
├── css
│ ├── custom.css
├── js
│ ├── custom.bottom.js
│ ├── custom.top.js
```
* A project can create these in the project dir in order to overwrite them. See
https://gohugo.io/themes/customizing/#override-static-files from more
information.
* In addition the following arrays may be files with paths or URLS
```toml
custom_css = [ "css/custom_foo.css", "https://cdnjs.cloudflare.com/ajax/libs/minireset.css/0.0.2/minireset.min.css" ]
custom_js_top = [ "js/custom_top_bar.js" ]
custom_js_bottom = [ "js/custom_bottom_foo.js", "https://cdn.jsdelivr.net/npm/js-cookie@2/src/js.cookie.min.js" ]
```
```toml
[params]
# used in layouts/partials/head.stylesheets.html
# used in layouts/partials/scripts.bottom.html
# used in layouts/partials/scripts.top.html
custom_css = [ ]
custom_js_top = [ ]
custom_js_bottom = [ ]
```
## Front Matter
archetypes:
```
blog.md
pages.md
```
### Pages, Blogs
```yaml
---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
toc: false
icon: "fab fa-font-awesome"
resImgTeaser: "teaser.png"
#resImgCmd:
#resImgOpt:
description: >
I'm an **example** description.
I'll show in teaser instead of (calculated) summary.
tags:
- "example tag 1"
- "example tag 2"
categories:
- "example cat 1"
- "example cat 2"
---
```
* for pages add:
```yaml
weight: 42
```
### content/pages/*/_index.md
```yaml
---
weight: 24
title: "My **Stuff** :house:"
date: 2017-11-13T15:37:04+01:00
resImgTeaser: teaserpics/gohugo.io/golang-a-closer-look.png
icon: "fas fa-list"
---
```
* this defines how the page navigation entries look like. See [Pages Navigation](#pages-navigation) for more.
## Shortcodes
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/
```
layouts/shortcodes/
├── alert.html
├── asciicast.html
├── classify.html
├── csc.html
├── cscb.html
├── hc.html
├── heg-figure.html
├── heg-gallery.html
├── heg-load-photoswipe.html
├── html-tag-classes.html
├── html-tag.html
├── html-tags.html
├── i18n.html
├── icon.html
├── kbd.html
├── liti.html
├── litt.html
├── litx.html
├── readfile.html
├── res-attach.html
├── res-debug.html
├── res-figure.html
├── res-gallery.html
├── res-gallery-load-photoswipe.html
├── w3-alert-icon.html
├── w3-badge.html
├── w3-button-icon.html
├── w3-code.html
├── w3-codespan.html
├── w3-notice-icon.html
├── w3-quote.html
└── w3-tag.html
```
* currently experimental are:
* [List by Title](https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#liti-list-by-title)
* [List by Taxonomy / Term](https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#litt-list-by-taxonomy-term-just-one-result)
* [List by Taxonomy with search](https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#litx-list-by-taxonomy-full-search)
## Page Resources
* https://gohugo.io/content-management/page-resources/
### Headless Images
* images may be stored as resource for a headless page:
* those images may be used for
* teaserpics (resImgTeaser)
* figures (res-figure)
* gallery (res-gallery)
* pictures for jumbotron, photocards, testimonials
* the path for the default (global) headless page is configurable
`config.toml`
```toml
[params.resources]
defaultResPagePath = "resources/images"
[params.resFigure]
defaultResPagePath = "."
[params.resGallery]
defaultResPagePath = "resources/images"
```
`content/resources/images/index.md`
```yaml
---
title: "headless-images"
headless: true
---
```
```
content/resources/images/
├── clients
│ └── pixabay.com
├── favicons
├── jumbotrons
│ └── pixabay.com
├── photocards
│ └── pixabay.com
├── teaserpics
│ ├── bitbucket.org
│ ├── gohugo.io
│ ├── pixabay.com
│ └── wikipedia.org
└── testimonials
└── pixabay.com
```
* A new headless page with the resources may be given in front matter via
`resImgRelPath`
```yaml
---
resImgRelPath: "../img/"
resImgTeaser: "dwh-1.jpg"
---
```
* And of course the page itself may have the image resources (which overrides an
image with the same name on the default (global) headless page)
Given a front matter
```yaml
resImgTeaser: teaserpics/pixabay.com/paint-2985569_640.jpg
```
The images is processed using hugo's build in image commands (resize to a reasonable size).
`layouts/partials/main.teaserpic.single.html`
```
{{- $myImgStyle := "max-width:400px; max-height:200px; width: auto; height: auto; margin: 8px 0px 8px 8px; " }}
{{- $myImg := .Param `resImgTeaser` }}
{{- $myImgCmd := .Param `resImgTeaserCmd` | default `Resize` }}
{{- $myImgOpt := .Param `resImgTeaserOpt` | default `300x` }}
```
### Images
* https://gohugo.io/content-management/image-processing/
* Support via shortcode `res-figure`
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/showcase/image-processing-with-hugo/
### Attachments
* Support via shortcode `res-attach`
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/showcase/attach-page-resources/
## Include Files
* Inspired by https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/readfile.html
* Reads a file (or directory) and optionally renders it using markdownify or highlight
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#readfile
```
{{}}
```
=>
```
content/.
Lrwxrwxrwx 2018-04-06 15 README.md
drwxrwxr-x 2018-04-06 blog
-rw-rw-r-- 2018-04-13 972 contact.md
-rw-rw-r-- 2018-04-13 5407 faq.md
drwxrwxr-x 2018-04-13 pages
-rw-rw-r-- 2018-04-13 190 search.md
```
```
{{}}
```
=> include a markdownified markdown file
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/readme/
## Gallery
### Gallery with image processing
* uses page resources and image processing
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#res-gallery for documentation and examples
[](https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/images-taken-from/gohugoio-teaserpics/)
### Hugo Easy Gallery
* https://github.com/liwenyip/hugo-easy-gallery/
`content/pages/showcase/gallery-01.md`
```yaml
---
title: "Gallery pixabay.com"
date: 2018-01-05T20:30:54+01:00
resImgTeaser: teaserpics/pixabay.com/paint-2985569_640.jpg
icon: "fas fa-images"
description: "Pictures from pixabay.com"
tags:
- Showcase
categories:
- This Theme
---
{{< heg-load-photoswipe >}}
{{< heg-gallery dir="/images/photocards/pixabay.com" caption-effect="none" hover-effect="grow" />}}
```
* This themes version of `{{}}` improves the caption's configuration (filename):
* show file extensions - or not
* do humanize - or not
* the values below are the defaults:
```toml
[params.gallery]
# used in layouts/shortcodes/heg-gallery.html
# showFileExtension = true
# humanizeCaption = false
```
## Figure
### Figure with image processing
* uses page resources and image processing
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#res-figure for documentation an examples
### Hugo Easy Gallery Figure
```
{{< heg-load-photoswipe >}}
{{< heg-figure link="/images/photocards/pixabay.com/04-photocard.jpg" caption-position="bottom" caption-effect="none" width="640px" caption="figure caption 4" attr="(c) by bar 4" attrlink="https://www.example.com" >}}
```
* This themes version of `{{}}` improves the
usage of `title caption attr attrlink` which are all optional
```
caption="figure caption 4" attr="(c) by bar 4" attrlink="https://www.example.com"
```
* Shown on page
* Shown with PhotoSwipe
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/hugo-theme-w3css-basic/page-shortcodes/#heg-figure for more examples
## Showcase
* See https://it-gro.github.io/hugo-theme-w3css-basic.github.io/pages/showcase/ for more examples
## Usage
To see the exampleSite use:
```bash
$ cd exampleSite/
$ export GoogleMapsApiKey=GEeawyBOuzOPzbFGizHKGReghibngUZTGjlioZM
$ hugo server -w --disableFastRender --navigateToChanged --themesDir ../../
```
Now enter [`localhost:1313`](http://localhost:1313) in the address bar of your browser.
For more information check out the official [Hugo documentation](http://gohugo.io/overview/usage/).
### Minifier
If you change the theme `w3css-basic.min.css`, `syntax.min.css` or
`front.js`, you have to apply a minifier. E.g.:
```bash
cd themes/hugo-theme-w3css-basic/static/css
yui-compressor --verbose --type css --line-break 1023 w3css-basic.css -o w3css-basic.min.css
yui-compressor --verbose --type css --line-break 1023 syntax.css -o syntax.min.css
cd -
cd themes/hugo-theme-w3css-basic/static/js
yui-compressor --verbose --type js --line-break 1023 --nomunge --preserve-semi front.js -o front.min.js
cd -
```
or change the file names in
`layouts/partials/head.stylesheets.html` and `layouts/partials/scripts.html`
## Workarounds
### summaryLength
* `summaryLength` was not configurable until hugo version 0.30
* `teaserTruncateSummary` was my workaround. But I think it still make
sense since summaryLength is in words and teaserTruncateSummary is in
characters.
* see [Summary](#summary)
### Shortcode output wrapped in <p>
[hugo/issues/1642: Shortcode output wrapped in <p> tags](https://github.com/gohugoio/hugo/issues/1642)
`layouts/_default/baseof.html`
```
{{ .Content | replaceRE `(?s: