From 1709438f46ebd9878ff07800684318ed948d2faa Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 13 Oct 2022 12:30:22 +0200 Subject: [PATCH 1/4] Shortcodes for tabbed panes: improved whitespace handling --- layouts/shortcodes/tab.html | 96 +++++++------- layouts/shortcodes/tabpane.html | 217 ++++++++++++++++---------------- 2 files changed, 155 insertions(+), 158 deletions(-) diff --git a/layouts/shortcodes/tab.html b/layouts/shortcodes/tab.html index c947ac48c0..8ec7e09d5e 100644 --- a/layouts/shortcodes/tab.html +++ b/layouts/shortcodes/tab.html @@ -1,52 +1,52 @@ - -{{ with $.Parent }} - {{- if ne $.Parent.Name "tabpane" -}} - {{- errorf "shortcode 'tab' must be used within a 'tabpane' block" -}} - {{- end -}} -{{- end -}} +{{- /* Make sure that we are enclosed within a tabpane shortcode block */ -}} +{{ with $.Parent -}} +{{ if ne $.Parent.Name "tabpane" -}} + {{ errorf "shortcode 'tab' must be used within a 'tabpane' block" -}} + {{ end -}} +{{ end -}} -{{ $header := "Tab" }} -{{ if and (not .IsNamedParams) (.Get 0) }} - {{ $header = (.Get 0) }} -{{ else }} - - {{ $header = default (printf "Tab %v" ( add $.Ordinal 1)) (.Get "header") }} -{{ end }} +{{ $header := "Tab" -}} +{{ if and (not .IsNamedParams) (.Get 0) -}} + {{ $header = (.Get 0) -}} +{{ else -}} + {{/* Prefill header if not given as named or unnamed parameter */ -}} + {{ $header = default (printf "Tab %v" ( add $.Ordinal 1)) (.Get "header") -}} +{{ end -}} - -{{ $tab := dict "header" $header }} -{{ with $.Get "lang" }} - {{ $tab = merge $tab (dict "language" ($.Get "lang")) }} -{{ end }} -{{ with $.Get "highlight" }} - {{ $tab = merge $tab (dict "highlight" ($.Get "highlight")) }} -{{ end }} -{{ with $.Get "text" }} - {{ if ne ( printf "%T" . ) "bool" }} - {{- errorf "shortcode tab: parameter 'text' must be either true or false" -}} - {{ end }} - {{ $tab = merge $tab (dict "text" ($.Get "text")) }} -{{ end }} -{{ with $.Get "right" }} - {{ if ne ( printf "%T" . ) "bool" }} - {{- errorf "shortcode tab: parameter 'right' must be either true or false" -}} - {{ end }} - {{ $tab = merge $tab (dict "rightpush" ($.Get "right")) }} -{{ end }} -{{ with $.Get "disabled" }} - {{ if ne ( printf "%T" . ) "bool" }} - {{- errorf "shortcode tab: parameter 'disabled' must be either true or false" -}} - {{ end }} - {{ $tab = merge $tab (dict "disabled" ($.Get "disabled")) }} -{{ end }} +{{/* store all tab info in dict tab */ -}} +{{ $tab := dict "header" $header -}} +{{ with $.Get "lang" -}} + {{ $tab = merge $tab (dict "language" ($.Get "lang")) -}} +{{ end -}} +{{ with $.Get "highlight" -}} + {{ $tab = merge $tab (dict "highlight" ($.Get "highlight")) -}} +{{ end -}} +{{ with $.Get "text" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tab: parameter 'text' must be either true or false" -}} + {{ end -}} + {{ $tab = merge $tab (dict "text" ($.Get "text")) -}} +{{ end -}} +{{ with $.Get "right" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tab: parameter 'right' must be either true or false" -}} + {{ end -}} + {{ $tab = merge $tab (dict "rightpush" ($.Get "right")) -}} +{{ end -}} +{{ with $.Get "disabled" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tab: parameter 'disabled' must be either true or false" -}} + {{ end -}} + {{ $tab = merge $tab (dict "disabled" ($.Get "disabled")) -}} +{{ end -}} -{{ with $.Inner }} - - {{ $tab = merge $tab (dict "content" $.Inner ) }} -{{ end }} +{{ with $.Inner -}} + {{/* Trim any leading and trailing newlines from .Inner, this avoids + spurious lines during syntax highlighting */ -}} + {{ $tab = merge $tab (dict "content" $.Inner) -}} +{{ end -}} - -{{ with .Parent }} - {{- $.Parent.Scratch.SetInMap "tabs" (printf "%02v" $.Ordinal) $tab -}} -{{ end }} +{{/* add dict tab to parent's scratchpad */ -}} +{{ with .Parent -}} + {{ $.Parent.Scratch.SetInMap "tabs" (printf "%02v" $.Ordinal) $tab -}} +{{ end -}} diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html index 4836f62675..a25aab1e32 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/shortcodes/tabpane.html @@ -1,130 +1,127 @@ - -{{ with .Get "langEqualsHeader" }} -{{ if ne ( printf "%T" . ) "bool" }} -{{- errorf "shortcode tabpane: parameter 'langEqualsHeader' must be either true or false" -}} -{{ end }} -{{ end }} - -{{ with .Get "text" }} -{{ if ne ( printf "%T" . ) "bool" }} -{{- errorf "shortcode tabpane: parameter 'text' must be either true or false" -}} -{{ end }} -{{ end }} - -{{ with .Get "persistLang" }} -{{ if ne ( printf "%T" . ) "bool" }} -{{- errorf "shortcode tabpane: parameter 'persistLang' must be either true or false" -}} -{{ end }} -{{ end }} - -{{ with .Get "right" }} -{{ if ne ( printf "%T" . ) "bool" }} -{{- errorf "shortcode tabpane: parameter 'right' must be either true or false" -}} -{{ end }} -{{ end }} - - -{{- $langPane := default "" ($.Get "lang") -}} -{{- $hloptionsPane := default "" ($.Get "highlight") -}} -{{- $textPane := default false ($.Get "text") -}} -{{- $langEqualsHeader := default false ($.Get "langEqualsHeader") -}} -{{- $persistLang := default true ($.Get "persistLang") -}} -{{- $rightPane := default false ($.Get "right") -}} -{{- $disabled := false -}} -{{- $rightpush := false -}} -{{- $activeSet := false -}} - - +{{/* Check parameter types */ -}} +{{ with .Get "langEqualsHeader" -}} +{{ if ne ( printf "%T" . ) "bool" -}} +{{ errorf "shortcode tabpane: parameter 'langEqualsHeader' must be either true or false" -}} +{{ end -}} +{{ end -}} + +{{ with .Get "text" -}} +{{ if ne ( printf "%T" . ) "bool" -}} +{{ errorf "shortcode tabpane: parameter 'text' must be either true or false" -}} +{{ end -}} +{{ end -}} + +{{ with .Get "persistLang" -}} +{{ if ne ( printf "%T" . ) "bool" -}} +{{ errorf "shortcode tabpane: parameter 'persistLang' must be either true or false" -}} +{{ end -}} +{{ end -}} + +{{ with .Get "right" -}} +{{ if ne ( printf "%T" . ) "bool" -}} +{{ errorf "shortcode tabpane: parameter 'right' must be either true or false" -}} +{{ end -}} +{{ end -}} + +{{/* Set values given defined within tabpane */ -}} +{{ $langPane := default "" ($.Get "lang") -}} +{{ $hloptionsPane := default "" ($.Get "highlight") -}} +{{ $textPane := default false ($.Get "text") -}} +{{ $langEqualsHeader := default false ($.Get "langEqualsHeader") -}} +{{ $persistLang := default true ($.Get "persistLang") -}} +{{ $rightPane := default false ($.Get "right") -}} +{{ $disabled := false -}} +{{ $rightpush := false -}} +{{ $activeSet := false -}} +{{- /* Scratchpad gets populated through call to .Inner */ -}} {{- .Inner -}} -{{ $activeSet = false }} +{{ $activeSet = false -}} - -
+{{/* Inner content */ -}} +
{{- range $index, $element := $.Scratch.Get "tabs" -}} - {{- $lang := $langPane -}} - {{- if $langEqualsHeader -}} - {{- $lang = $element.header -}} - {{end}} - {{- with $element.language -}} - {{- $lang = $element.language -}} - {{- end -}} - - {{- $disabled := false -}} - {{- with $element.disabled -}} - {{- $disabled = . }} - {{- end -}} - - {{- $hloptions := $hloptionsPane -}} - {{- with $element.highlight -}} - {{- $hloptions = $element.highlight -}} - {{- end -}} - - {{- $text := $textPane -}} - {{- with $element.text -}} - {{- $text = . }} - {{- end -}} - - {{- $tabid := printf "tabs-%02v-%v-tab" $.Ordinal $index | anchorize -}} - {{- $entryid := printf "tabs-%02v-%v" $.Ordinal $index | anchorize -}} - + {{ $lang := $langPane -}} + {{ if $langEqualsHeader -}} + {{ $lang = $element.header -}} + {{ end -}} + {{ with $element.language -}} + {{ $lang = $element.language -}} + {{ end -}} + + {{ $disabled := false -}} + {{ with $element.disabled -}} + {{ $disabled = . -}} + {{ end -}} + + {{ $hloptions := $hloptionsPane -}} + {{ with $element.highlight -}} + {{ $hloptions = $element.highlight -}} + {{ end -}} + + {{ $text := $textPane -}} + {{ with $element.text -}} + {{ $text = . }} + {{ end -}} + + {{ $tabid := printf "tabs-%02v-%v-tab" $.Ordinal $index | anchorize -}} + {{ $entryid := printf "tabs-%02v-%v" $.Ordinal $index | anchorize }}
- {{ if $text }} - {{- index . "content" -}} - {{- else -}} - {{- highlight (trim (index . "content") "\n") $lang $hloptions -}} - {{- end -}} + {{ if $text -}} + {{ index . "content" -}} + {{ else -}} + {{ highlight (trim (index . "content") "\n") $lang $hloptions -}} + {{ end }}
- {{ if not $disabled }} - {{ $activeSet = true }} - {{ end }} + {{- if not $disabled -}} + {{ $activeSet = true -}} + {{ end -}} - {{ end }} + {{- end }}
From d9f9531e464c633c195e48591ec2a801c3012dcc Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Fri, 14 Oct 2022 08:35:51 +0200 Subject: [PATCH 2/4] Fix: Tabpane shows multiple tabs at the same time #1271 --- assets/scss/shortcodes/tabbed-pane.scss | 24 ++++++----- layouts/shortcodes/tabpane.html | 56 ++++++++++++++++--------- 2 files changed, 50 insertions(+), 30 deletions(-) diff --git a/assets/scss/shortcodes/tabbed-pane.scss b/assets/scss/shortcodes/tabbed-pane.scss index f63b50d064..65096aee6e 100644 --- a/assets/scss/shortcodes/tabbed-pane.scss +++ b/assets/scss/shortcodes/tabbed-pane.scss @@ -1,14 +1,17 @@ .tab-content { - .highlight { - margin: 0rem 0 2rem 0; + .tab-pane { + pre { + margin: 0rem 0 0rem 0; + } } } + .tab-content { .tab-pane { .highlight { - margin: 0rem 0 0rem 0; - border: none; - max-width: 100%; + margin: 0rem 0 0rem 0; + border: none; + max-width: 100%; } margin-top: 0rem; margin-bottom: 1.5rem; @@ -16,7 +19,7 @@ border-left: 1px solid rgba(0, 0, 0, 0.125); border-right: 1px solid rgba(0, 0, 0, 0.125); border-bottom: 1px solid rgba(0, 0, 0, 0.125); - } + } } .tab-body { @@ -27,10 +30,9 @@ padding: 1.5rem; @each $color, $value in $theme-colors { - &-#{$color} { - - border-style: solid; - border-color: $value; - } + &-#{$color} { + border-style: solid; + border-color: $value; + } } } diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html index a25aab1e32..de644ea076 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/shortcodes/tabpane.html @@ -1,26 +1,26 @@ {{/* Check parameter types */ -}} {{ with .Get "langEqualsHeader" -}} -{{ if ne ( printf "%T" . ) "bool" -}} -{{ errorf "shortcode tabpane: parameter 'langEqualsHeader' must be either true or false" -}} -{{ end -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tabpane: parameter 'langEqualsHeader' must be either true or false" -}} + {{ end -}} {{ end -}} {{ with .Get "text" -}} -{{ if ne ( printf "%T" . ) "bool" -}} -{{ errorf "shortcode tabpane: parameter 'text' must be either true or false" -}} -{{ end -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tabpane: parameter 'text' must be either true or false" -}} + {{ end -}} {{ end -}} {{ with .Get "persistLang" -}} -{{ if ne ( printf "%T" . ) "bool" -}} -{{ errorf "shortcode tabpane: parameter 'persistLang' must be either true or false" -}} -{{ end -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tabpane: parameter 'persistLang' must be either true or false" -}} + {{ end -}} {{ end -}} {{ with .Get "right" -}} -{{ if ne ( printf "%T" . ) "bool" -}} -{{ errorf "shortcode tabpane: parameter 'right' must be either true or false" -}} -{{ end -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "shortcode tabpane: parameter 'right' must be either true or false" -}} + {{ end -}} {{ end -}} {{/* Set values given defined within tabpane */ -}} @@ -30,15 +30,22 @@ {{ $langEqualsHeader := default false ($.Get "langEqualsHeader") -}} {{ $persistLang := default true ($.Get "persistLang") -}} {{ $rightPane := default false ($.Get "right") -}} -{{ $disabled := false -}} -{{ $rightpush := false -}} {{ $activeSet := false -}} {{- /* Scratchpad gets populated through call to .Inner */ -}} {{- .Inner -}} +{{ $langs := slice -}} +{{ $duplicate := false -}} +{{ $duplicateLang := "" -}} + +{{ if $duplicate -}} + {{ warnf "Tabpane on page '%s': duplicate language '%s' detected, disabling persistance of language to avoid multiple tab display." .Page.Title $duplicateLang -}} +{{ end -}} +{{ $duplicate = false -}} +{{ $langs = slice -}} {{ $activeSet = false -}} {{/* Inner content */ -}} From c8a99bcc61d107ee7095c478f55a05006271fecd Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Fri, 14 Oct 2022 08:41:24 +0200 Subject: [PATCH 3/4] User guide: fix invalid html by adding alt attribute to image Remove trailing whitespace in a few .md files --- userguide/content/en/docs/Language/_index.md | 2 +- .../en/docs/adding-content/shortcodes/index.md | 4 ++-- .../content/en/docs/adding-content/taxonomy.md | 8 ++++---- .../content/en/docs/adding-content/versioning.md | 14 +++++++------- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/userguide/content/en/docs/Language/_index.md b/userguide/content/en/docs/Language/_index.md index fd5bbcbc06..04ba1387b8 100644 --- a/userguide/content/en/docs/Language/_index.md +++ b/userguide/content/en/docs/Language/_index.md @@ -98,7 +98,7 @@ If you configure more than one language in `config.toml`, the Docsy theme adds a ## Internationalization bundles -All UI strings (text for buttons etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language. +All UI strings (text for buttons etc.) are bundled inside `/i18n` in the theme, with a `.toml` file for each language. If your chosen language isn't currently in the theme and you create your own `.toml` file for all the common UI strings (for example, if you translate the UI text into Japanese and create a copy of `en.toml` called `jp.toml`), we recommend you do this **in the theme** rather than in your own project, so it can be reused by others. Any additional strings or overridden values can be added to your project's `/i18n` folder. diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index 6a3b26e447..2f9731edbd 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -403,7 +403,7 @@ The Docsy template provides two shortcodes `tabpane` and `tab` that let you easi {{%/* /tab */%}} {{}} Herzlich willkommen! - + Flag Germany {{}} {{%/* tab header="Swahili" lang="sw" */%}} ![Flag Tanzania](flags/tz.png) @@ -422,7 +422,7 @@ This code translates to the right aligned tabbed pane below, showing a `Welcome! {{% /tab %}} {{< tab header="German" lang="de" >}} Herzlich willkommen! - + Flag Germany {{< /tab >}} {{% tab header="Swahili" lang="sw" %}} ![Flag Tanzania](flags/tz.png) diff --git a/userguide/content/en/docs/adding-content/taxonomy.md b/userguide/content/en/docs/adding-content/taxonomy.md index d4316d5fe7..94785d0ded 100644 --- a/userguide/content/en/docs/adding-content/taxonomy.md +++ b/userguide/content/en/docs/adding-content/taxonomy.md @@ -8,7 +8,7 @@ description: > Structure the content using taxonomies like tags, categories, labels. --- -Docsy supports Hugo's Taxonomies (see: https://gohugo.io/content-management/taxonomies/) in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page. +Docsy supports Hugo's Taxonomies (see: https://gohugo.io/content-management/taxonomies/) in its docs and blog section. You can see the default layout and can test the behavior of the generated links on this page. ## Terminology @@ -125,11 +125,11 @@ params: {{< /tab >}} {{< /tabpane >}} -The settings above would only show a taxonomy cloud for `projects` and `tags` (with the headlines "Our Projects" and "Tag Cloud") in Docsy's right sidebar and the assigned terms for the taxonomies `tags` and `categories` for each page. +The settings above would only show a taxonomy cloud for `projects` and `tags` (with the headlines "Our Projects" and "Tag Cloud") in Docsy's right sidebar and the assigned terms for the taxonomies `tags` and `categories` for each page. -To disable any taxonomy cloud you have to set the Parameter `taxonomyCloud = []` resp. if you don't want to show the assigned terms you have to set `taxonomyPageHeader = []`. +To disable any taxonomy cloud you have to set the Parameter `taxonomyCloud = []` resp. if you don't want to show the assigned terms you have to set `taxonomyPageHeader = []`. -As default the plural label of a taxonomy is used as it cloud title. You can overwrite the default cloud title with `taxonomyCloudTitle`. But if you do so, you have to define a manual title for each enabled taxonomy cloud (`taxonomyCloud` and `taxonomyCloudTitle` must have the same length!). +As default the plural label of a taxonomy is used as it cloud title. You can overwrite the default cloud title with `taxonomyCloudTitle`. But if you do so, you have to define a manual title for each enabled taxonomy cloud (`taxonomyCloud` and `taxonomyCloudTitle` must have the same length!). If you don't set the parameters `taxonomyCloud` resp. `taxonomyPageHeader` the taxonomy clouds resp. assigned terms for all defined taxonomies will be generated. ## Partials diff --git a/userguide/content/en/docs/adding-content/versioning.md b/userguide/content/en/docs/adding-content/versioning.md index 0f1234c647..340a0fb70a 100644 --- a/userguide/content/en/docs/adding-content/versioning.md +++ b/userguide/content/en/docs/adding-content/versioning.md @@ -14,8 +14,8 @@ to display an information banner on the archived sites. ## Adding a version drop-down menu -If you add some `[params.versions]` in `config.toml`/`config.yaml`/`config.json`, the Docsy theme adds a -version selector drop down to the top-level menu. You specify a URL and a name +If you add some `[params.versions]` in `config.toml`/`config.yaml`/`config.json`, the Docsy theme adds a +version selector drop down to the top-level menu. You specify a URL and a name for each version you would like to add to the menu, as in the following example: {{< tabpane persistLang=false >}} @@ -84,7 +84,7 @@ version_menu: 'Releases' {{< /tab >}} {{< /tabpane >}} -If you set the `version_menu_pagelinks` parameter to `true`, then links in the version drop-down menu +If you set the `version_menu_pagelinks` parameter to `true`, then links in the version drop-down menu point to the current page in the other version, instead of the main page. This can be useful if the document doesn't change much between the different versions. Note that if the current page doesn't exist in the other version, the link will be broken. @@ -94,12 +94,12 @@ You can read more about Docsy menus in the guide to ## Displaying a banner on archived doc sites -If you create archived snapshots for older versions of your docs, you can add a +If you create archived snapshots for older versions of your docs, you can add a note at the top of every page in the archived docs to let readers know that -they’re seeing an unmaintained snapshot and give them a link to the latest +they’re seeing an unmaintained snapshot and give them a link to the latest version. -For example, see the archived docs for +For example, see the archived docs for [Kubeflow v0.6](https://v0-6.kubeflow.org/docs/):
@@ -145,7 +145,7 @@ version: '0.1' {{< /tabpane >}} 1. Make sure that `url_latest_version` contains the URL of the website that you - want to point readers to. In most cases, this should be the URL of the latest + want to point readers to. In most cases, this should be the URL of the latest version of your docs: {{< tabpane persistLang=false >}} From fe18d4472345392a3b3314674ee36e53f87924be Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Wed, 19 Oct 2022 16:27:39 +0200 Subject: [PATCH 4/4] Tabbed pane, fix: avoid duplicate html id if content is pulled in via readfile shortcode (#1289) --- layouts/shortcodes/readfile.html | 9 +++++++-- layouts/shortcodes/tabpane.html | 19 +++++++++++++------ 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html index f97541c598..7d27caa35a 100644 --- a/layouts/shortcodes/readfile.html +++ b/layouts/shortcodes/readfile.html @@ -1,3 +1,8 @@ +{{/* Store ordinal, to be retrieved by parent element */}} +{{ if ge hugo.Version "0.93.0" }} + {{ .Page.Store.Add "Ordinal" 1 }} +{{ end }} + {{/* Handle the "file" named parameter or a single unnamed parameter as the file path */}} {{ if .IsNamedParams }} @@ -24,10 +29,10 @@ {{ if fileExists ($.Scratch.Get "filepath") }} {{ if eq (.Get "code") "true" }} - {{- highlight ($.Scratch.Get "filepath" | readFile | htmlUnescape | + {{- highlight ($.Scratch.Get "filepath" | readFile | htmlUnescape | safeHTML ) (.Get "lang") "" -}} {{ else }} - {{- $.Scratch.Get "filepath" | readFile | .Page.RenderString | htmlUnescape | safeHTML -}} + {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | htmlUnescape | safeHTML -}} {{ end }} {{ else }} diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html index de644ea076..1c38affdc7 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/shortcodes/tabpane.html @@ -38,7 +38,14 @@ {{ $duplicate := false -}} {{ $duplicateLang := "" -}} -