From 2c11f5365392945cc49a1220d8fea074b225b6ca Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Fri, 14 Oct 2022 17:23:14 +0200 Subject: [PATCH 01/76] Add render hook for 'chem' code blocks Auto activation of `math' and 'chem' blocks Add ability to enable KateX and/or mhchem for individual pages only Upgrade to KaTeX 0.16.3 --- .../_markup/render-codeblock-chem.html | 18 ++ .../_markup/render-codeblock-math.html | 28 +-- layouts/partials/scripts.html | 50 +++-- .../diagrams-and-formulae/index.md | 182 +++++++++++++----- 4 files changed, 192 insertions(+), 86 deletions(-) create mode 100644 layouts/_default/_markup/render-codeblock-chem.html diff --git a/layouts/_default/_markup/render-codeblock-chem.html b/layouts/_default/_markup/render-codeblock-chem.html new file mode 100644 index 0000000000..1480857725 --- /dev/null +++ b/layouts/_default/_markup/render-codeblock-chem.html @@ -0,0 +1,18 @@ +{{ .Page.Store.Set "hasmhchem" true -}} + +{{/* set default delimiters */ -}} +{{ $delimiter_left := "$$" -}} +{{ $delimiter_right := "$$" -}} + +{{/* override delimiters if set in config file */ -}} +{{ with $.Page.Site.Params.katex.options.delimiters -}} + {{ range first 1 ( where . "display" true ) -}} + {{ $delimiter_left = index . "left" -}} + {{ $delimiter_right = index . "right" -}} + {{ end -}} +{{ end -}} + +{{/* output of chemical formulae */}} +
{{ $delimiter_left -}} +{{ .Inner | safeHTML -}} +{{ $delimiter_right -}}
{{ "" -}} diff --git a/layouts/_default/_markup/render-codeblock-math.html b/layouts/_default/_markup/render-codeblock-math.html index 831b9a2f6b..8308694906 100644 --- a/layouts/_default/_markup/render-codeblock-math.html +++ b/layouts/_default/_markup/render-codeblock-math.html @@ -1,16 +1,18 @@ -{{/* set default delimiters */}} -{{ $delimiter_left := "$$" }} -{{ $delimiter_right := "$$" }} +{{ .Page.Store.Set "hasKaTeX" true -}} -{{/* override delimiters if set in config file */}} -{{ with $.Page.Site.Params.katex.options.delimiters }} - {{ range first 1 ( where . "display" true ) }} - {{ $delimiter_left = index . "left" }} - {{ $delimiter_right = index . "right" }} - {{ end }} -{{end}} +{{/* set default delimiters */ -}} +{{ $delimiter_left := "$$" -}} +{{ $delimiter_right := "$$" -}} + +{{/* override delimiters if set in config file */ -}} +{{ with $.Page.Site.Params.katex.options.delimiters -}} + {{ range first 1 ( where . "display" true ) -}} + {{ $delimiter_left = index . "left" -}} + {{ $delimiter_right = index . "right" -}} + {{ end -}} +{{ end -}} {{/* output of equation */}} -

{{ $delimiter_left }} -{{ .Inner | safeHTML }} -{{ $delimiter_right }}

+
{{ $delimiter_left -}} +{{ .Inner | safeHTML -}} +{{ $delimiter_right }}
{{ "" -}} \ No newline at end of file diff --git a/layouts/partials/scripts.html b/layouts/partials/scripts.html index f86ea4d96b..e225a0464a 100644 --- a/layouts/partials/scripts.html +++ b/layouts/partials/scripts.html @@ -1,10 +1,16 @@ +{{ $needKaTeX := or .Site.Params.katex.enable .Params.math .Params.chem -}} +{{ $needmhchem := or .Site.Params.katex.mhchem.enable .Params.chem -}} {{ $needmermaid := .Site.Params.mermaid.enable -}} {{ if ge hugo.Version "0.93.0" -}} {{ with .Site.Params.mermaid }} {{ $needmermaid = true }} {{ end }} - {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}} -{{ end }} + {{ $needmermaid = or $needmermaid (.Page.Store.Get "hasmermaid") -}} +{{ else -}} + {{ if or $needKaTeX $needmhchem $needmermaid -}} + {{ warnf "Outdated Hugo version %s, consider upgrading to make full use of all theme features" hugo.Version }} + {{ end -}} +{{ end -}} {{ if .Site.Params.markmap.enable -}} -{{ end }} -
-
-
-
-
- {{ with .Get "title" }}

{{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}{{ end }}{{ $title | html }}

{{ end }} - {{ with .Get "subtitle" }}

{{ . | html }}

{{ end }} -
- {{ if eq .Page.File.Ext "md" }} - {{ .Inner | markdownify }} - {{ else }} - {{ .Inner | htmlUnescape | safeHTML }} - {{ end }} -
+{{ end -}} + +
+
+
+
+ {{ with .Get "title" }}

{{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}{{ end }}{{ $title | html }}

{{ end }} + {{ with .Get "subtitle" }}

{{ . | html }}

{{ end }} +
+ {{ if eq .Page.File.Ext "md" }} + {{ .Inner | markdownify }} + {{ else }} + {{ .Inner | htmlUnescape | safeHTML }} + {{ end }}
- {{ if $byline }} -
- {{ $byline }} -
- {{ end }} + {{ with .Get "byline" | default "" -}} +
{{ . }}
+ {{- end }}
+{{/**/ -}} diff --git a/userguide/content/en/_index.html b/userguide/content/en/_index.html index 835f233176..163ac94af6 100644 --- a/userguide/content/en/_index.html +++ b/userguide/content/en/_index.html @@ -2,7 +2,7 @@ title: Docsy --- -{{< blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" color="orange" >}} +{{< blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" >}}
}}"> Learn More diff --git a/userguide/content/en/docs/adding-content/iconsimages.md b/userguide/content/en/docs/adding-content/iconsimages.md index b14200bc87..94fc43b7da 100644 --- a/userguide/content/en/docs/adding-content/iconsimages.md +++ b/userguide/content/en/docs/adding-content/iconsimages.md @@ -57,7 +57,7 @@ Docsy's [`blocks/cover` shortcode](/docs/adding-content/shortcodes/#blockscover) You specify the preferred display height of a cover block container (and hence its image) using the block's `height` parameter. For a full viewport height, use `full`: ```html -{{}} +{{}} ... {{}} ``` From 7f0bc03fd2af389a2d75ec73ad7e5beda6a82bd1 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Wed, 8 Mar 2023 20:34:00 +0100 Subject: [PATCH 63/76] Shortcode 'blocks/lead' improvements (#1398) --- layouts/shortcodes/blocks/lead.html | 25 ++++++++-------- .../content/en/{_index.html => _index.md} | 29 ++++++++++--------- .../docs/adding-content/shortcodes/index.md | 27 +++++++++-------- 3 files changed, 43 insertions(+), 38 deletions(-) rename userguide/content/en/{_index.html => _index.md} (66%) diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html index bae22630d6..ea456af02a 100644 --- a/layouts/shortcodes/blocks/lead.html +++ b/layouts/shortcodes/blocks/lead.html @@ -1,16 +1,17 @@ -{{ $_hugo_config := `{ "version": 1 }` -}} {{ $col_id := .Get "color" | default .Ordinal -}} {{ $height := .Get "height" | default "auto" -}} -{{/* Height can be one of: auto, min, med, max, full. */ -}} - +{{ with .Get "height" -}} + {{ if not ( or ( eq . "auto" ) ( eq . "min" ) ( eq . "med" ) ( eq . "max" ) ( eq . "full" ) ) -}} + {{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}} + {{ end -}} +{{ end -}} +
-
-
- {{ if eq .Page.File.Ext "md" -}} - {{ .Inner | markdownify -}} - {{ else -}} - {{ .Inner | htmlUnescape | safeHTML -}} - {{ end -}} -
-
+
+
+{{/* Do NOT remove this comment! It ends above HTML block. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} +{{ .Inner }} +
+
+{{/**/ -}} diff --git a/userguide/content/en/_index.html b/userguide/content/en/_index.md similarity index 66% rename from userguide/content/en/_index.html rename to userguide/content/en/_index.md index 163ac94af6..84f03c857b 100644 --- a/userguide/content/en/_index.html +++ b/userguide/content/en/_index.md @@ -2,18 +2,19 @@ title: Docsy --- -{{< blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" >}} -
- }}"> - Learn More - - - Download - -

A Hugo theme for creating great technical documentation sites

- {{< blocks/link-down color="info" >}} -
-{{< /blocks/cover >}} +{{% blocks/cover title="Welcome to Docsy!" image_anchor="top" height="full" %}} + + Learn More + + + Download + + +A Hugo theme for creating great technical documentation sites +{.lead .mt-5} + +{{% blocks/link-down color="info" %}} +{{% /blocks/cover %}} {{% blocks/lead color="primary" %}} Docsy is a theme for the Hugo static site generator that's specifically designed @@ -26,7 +27,7 @@ {{% /blocks/lead %}} -{{< blocks/section color="dark" type="features">}} +{{% blocks/section color="dark" type="features"%}} {{% blocks/feature icon="fa-lightbulb" title="See Docsy in action!" url="/docs/examples/" %}} As well as our example site, there's a growing number of projects using Docsy for their doc sites. {{% /blocks/feature %}} @@ -41,4 +42,4 @@ Find out about new features and how our users are using Docsy. {{% /blocks/feature %}} -{{< /blocks/section >}} +{{% /blocks/section %}} diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index 6459fda71d..ef6ec3dd25 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -1,6 +1,6 @@ --- -title: "Docsy Shortcodes" -linkTitle: "Docsy Shortcodes" +title: Docsy Shortcodes +linkTitle: Shortcodes date: 2017-01-05 weight: 5 description: > @@ -13,6 +13,13 @@ resources: Rather than writing all your site pages from scratch, Hugo lets you define and use [shortcodes](https://gohugo.io/content-management/shortcodes/). These are reusable snippets of content that you can include in your pages, often using HTML to create effects that are difficult or impossible to do in simple Markdown. Shortcodes can also have parameters that let you, for example, add your own text to a fancy shortcode text box. As well as Hugo's [built-in shortcodes](https://gohugo.io/content-management/shortcodes/), Docsy provides some shortcodes of its own to help you build your pages. +## Shortcode delimiters + +As illustrated below, using the bracket styled [shortcode delimiter][], +`{{}}`, tells Hugo that the inner content is HTML/plain text and needs +no further processing. By using the delimiter `{{%/*...*/%}}`, Hugo will treat +the shortcode body as Markdown. You can use both styles in your pages. + ## Shortcode blocks The theme comes with a set of custom **Page Block** shortcodes that can be used to compose landing pages, about pages, and similar. @@ -48,11 +55,6 @@ The **blocks/cover** shortcode creates a landing page type of block that fills t Note that the relevant shortcode parameters above will have sensible defaults, but is included here for completeness. -{{% alert title="Hugo Tip" %}} -> Using the bracket styled shortcode delimiter, `>}}`, tells Hugo that the inner content is HTML/plain text and needs no further processing. Changing the delimiter to `%}}` means Hugo will treat the content as Markdown. You can use both styles in your pages. -{{% /alert %}} - - | Parameter | Default | Description | | ---------------- |------------| ------------| | title | | The main display title for the block. | @@ -82,10 +84,10 @@ Runs on **bare metal** in the **cloud**! {{%/* /blocks/lead */%}} ``` -| Parameter | Default | Description | -| ---------------- |------------| ------------| -| height | | See above. -| color | | See above. +| Parameter | Default | Description | +| --------- |--------- | ----------------------------------------- | +| height | `auto` | See [Shortcode blocks](#shortcode-blocks) | +| color | .Ordinal | See [Shortcode blocks](#shortcode-blocks) | ### blocks/section @@ -157,7 +159,6 @@ The **alert** shortcode creates an alert block that can be used to display notic {{%/* alert title="Warning" color="warning" */%}} This is a warning. {{%/* /alert */%}} - ``` Renders to: @@ -700,3 +701,5 @@ This text does not appear in the output if `buildCondition = "bar" is set in you ``` If you are using this shortcode, note that when evaluating the conditions, substring matches are matches as well. That means, if you set `include-if="foobar"`, and `buildcondition = "foo"`, you have a match! + +[shortcode delimiter]: https://gohugo.io/content-management/shortcodes/#use-shortcodes From d8bebad1e692eadb1eeaadae2bbf1b7a05bf91c5 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 8 Mar 2023 16:13:14 -0500 Subject: [PATCH 64/76] [BSv5] blocks/lead row-col hierarchy fix (#1469) --- layouts/shortcodes/blocks/lead.html | 2 ++ 1 file changed, 2 insertions(+) diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html index ea456af02a..1d68439d0d 100644 --- a/layouts/shortcodes/blocks/lead.html +++ b/layouts/shortcodes/blocks/lead.html @@ -7,11 +7,13 @@ {{ end -}}
+
{{/* Do NOT remove this comment! It ends above HTML block. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} {{ .Inner }}
+
{{/**/ -}} From 33e1a497f9550fb54290ef348a1a30afb109007f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 8 Mar 2023 17:27:03 -0500 Subject: [PATCH 65/76] [BSv5] community/list row-col hierarchy fix (#1471) --- layouts/community/list.html | 15 +++++++++------ layouts/shortcodes/blocks/cover.html | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/layouts/community/list.html b/layouts/community/list.html index b00ea01bef..1c8d2ffb2c 100644 --- a/layouts/community/list.html +++ b/layouts/community/list.html @@ -1,15 +1,18 @@ {{ define "main" -}} -
+
+
- -

{{ T "community_join" . }}

-

{{ T "community_introduce" . }}

- + +

{{ T "community_join" . }}

+

{{ T "community_introduce" . }}

+
+
- {{ partial "community_links.html" . -}} {{ with .Content -}} diff --git a/layouts/shortcodes/blocks/cover.html b/layouts/shortcodes/blocks/cover.html index c3e357f058..36790be4b0 100644 --- a/layouts/shortcodes/blocks/cover.html +++ b/layouts/shortcodes/blocks/cover.html @@ -28,7 +28,7 @@
-
+
{{ with .Get "title" }}

{{ $title := . }}{{ with $logo_image }}{{ $logo_image_resized := (.Fit (printf "70x70 %s" $logo_anchor)) }}{{ end }}{{ $title | html }}

{{ end }} From 01eafd35aa2f8c95fa1632bcc64b3c4fd014f8c2 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 9 Mar 2023 00:26:42 +0100 Subject: [PATCH 66/76] Avoid warning 'calling IsSet with unsupported type "invalid" ()' (#1465) --- layouts/partials/sidebar-tree.html | 8 ++++---- layouts/partials/sidebar.html | 6 +++--- layouts/partials/taxonomy_terms_article_wrapper.html | 4 ++-- layouts/partials/taxonomy_terms_clouds.html | 6 +++--- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/layouts/partials/sidebar-tree.html b/layouts/partials/sidebar-tree.html index eca2ab80a9..bebd3b59e0 100644 --- a/layouts/partials/sidebar-tree.html +++ b/layouts/partials/sidebar-tree.html @@ -1,5 +1,5 @@ -{{/* We cache this partial for bigger sites and set the active class client side. */}} -{{ $sidebarCacheLimit := cond (isset .Site.Params.ui "sidebar_cache_limit") .Site.Params.ui.sidebar_cache_limit 2000 -}} +{{/* We cache this partial for bigger sites and set the active class client side. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} {{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}}
{{ if not .Site.Params.ui.sidebar_search_disable -}} @@ -26,8 +26,8 @@ {{ end -}} {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection -}} {{ $ulNr := 0 -}} - {{ $ulShow := cond (isset .Site.Params.ui "ul_show") .Site.Params.ui.ul_show 1 -}} - {{ $sidebarMenuTruncate := cond (isset .Site.Params.ui "sidebar_menu_truncate") .Site.Params.ui.sidebar_menu_truncate 50 -}} + {{ $ulShow := .Site.Params.ui.ul_show | default 1 -}} + {{ $sidebarMenuTruncate := .Site.Params.ui.sidebar_menu_truncate | default 50 -}}
    {{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1)) }}
diff --git a/layouts/partials/sidebar.html b/layouts/partials/sidebar.html index 8d3fc5ae7b..83e149f30b 100644 --- a/layouts/partials/sidebar.html +++ b/layouts/partials/sidebar.html @@ -1,7 +1,7 @@ -{{/* The "active" toggle here may delay rendering, so we only cache this side bar menu for bigger sites. -*/}}{{ $sidebarCacheLimit := cond (isset .Site.Params.ui "sidebar_cache_limit") .Site.Params.ui.sidebar_cache_limit 2000 -}} +{{/* The "active" toggle here may delay rendering, so we only cache this side bar menu for bigger sites. */ -}} +{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}} {{ $shouldCache := ge (len .Site.Pages) $sidebarCacheLimit -}} -{{ $sidebarCacheTypeRoot := cond (isset .Site.Params.ui "sidebar_cache_type_root") .Site.Params.ui.sidebar_cache_type_root false -}} +{{ $sidebarCacheTypeRoot := .Site.Params.ui.sidebar_cache_type_root | default false -}} {{ if $shouldCache -}} {{ $mid := printf "m-%s" (.RelPermalink | anchorize) }} - -{{ end }} + +{{ end -}}
- -{{ end }} \ No newline at end of file +{{ end }} diff --git a/layouts/_default/single.html b/layouts/_default/single.html index b2e137af6f..8362338e45 100644 --- a/layouts/_default/single.html +++ b/layouts/_default/single.html @@ -1,5 +1,3 @@ -{{ define "main" }} -{{ with .Content }} -{{ . }} +{{ define "main" -}} +{{ .Content -}} {{ end }} -{{ end }} \ No newline at end of file diff --git a/layouts/community/list.html b/layouts/community/list.html index 1c8d2ffb2c..08e949e414 100644 --- a/layouts/community/list.html +++ b/layouts/community/list.html @@ -1,6 +1,6 @@ {{ define "main" -}} - +
diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html index 1d68439d0d..6c12d62037 100644 --- a/layouts/shortcodes/blocks/lead.html +++ b/layouts/shortcodes/blocks/lead.html @@ -5,12 +5,13 @@ {{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}} {{ end -}} {{ end -}} +
-{{/* Do NOT remove this comment! It ends above HTML block. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} +{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} {{ .Inner }}
diff --git a/layouts/shortcodes/blocks/section.html b/layouts/shortcodes/blocks/section.html index ed61e7e2a5..fbe8f8c7ec 100644 --- a/layouts/shortcodes/blocks/section.html +++ b/layouts/shortcodes/blocks/section.html @@ -1,16 +1,14 @@ -{{ $_hugo_config := `{ "version": 1 }` -}} {{ $col_id := .Get "color" | default .Ordinal -}} {{ $height := .Get "height" | default "auto" -}} -{{ $type := .Get "type" | default "" -}} - +{{ $type := .Get "type" | default "container" -}} + +
-
-
- {{ if eq .Page.File.Ext "md" -}} - {{ .Inner | markdownify -}} - {{ else -}} - {{ .Inner | htmlUnescape | safeHTML -}} - {{ end -}} -
-
+
+
+{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} +{{ .Inner -}} +
+
+{{/**/ -}} diff --git a/userguide/content/en/_index.md b/userguide/content/en/_index.md index 84f03c857b..8965d0a40b 100644 --- a/userguide/content/en/_index.md +++ b/userguide/content/en/_index.md @@ -27,7 +27,8 @@ on creating great content for your users. {{% /blocks/lead %}} -{{% blocks/section color="dark" type="features"%}} +{{% blocks/section color="dark" type="row" %}} + {{% blocks/feature icon="fa-lightbulb" title="See Docsy in action!" url="/docs/examples/" %}} As well as our example site, there's a growing number of projects using Docsy for their doc sites. {{% /blocks/feature %}} diff --git a/userguide/content/en/about/_index.md b/userguide/content/en/about/index.md similarity index 97% rename from userguide/content/en/about/_index.md rename to userguide/content/en/about/index.md index 8be99b5dc6..d92803f039 100644 --- a/userguide/content/en/about/_index.md +++ b/userguide/content/en/about/index.md @@ -2,7 +2,6 @@ title: About Docsy linkTitle: About menu: {main: {weight: 10}} -layout: docs --- {{% blocks/cover title="About Docsy" height="auto" %}} @@ -12,7 +11,7 @@ Docsy is a pre-configured Hugo theme that provides the core features and behavio Read on to find out more, or visit our [documentation](/docs/) to get started! {{% /blocks/cover %}} -{{% blocks/section type="section" color="primary" %}} +{{% blocks/section color="primary" %}} ## So what’s a technical documentation site? A technical documentation site is a website that your users can visit to find the documentation for your technical project. Your documentation set contains all the information you think your users might need to engage with your project, from overviews that help them understand what the project is for, to instructions for specific tasks. Depending on the size of the project, a documentation set can be a page or two or an entire “book” with different types of information. @@ -28,7 +27,7 @@ If you have users around the world, you might also want to provide your content Once you have your content, you use a technical documentation site to publish your technical documentation set online for your users. In addition to your documentation, your site might also contain material like contact information, a blog, or information about how to contribute to the project. {{% /blocks/section %}} -{{% blocks/section type="section" color="white" %}} +{{% blocks/section color="white" %}} ## How does Docsy help? Particularly when working with open source projects, it can be difficult to figure out how to turn all your product knowledge into a website that helps and engages your users. **Enter Docsy!** @@ -122,7 +121,7 @@ template, or even add new behaviors. [Learn more...](/docs/updating/) Because Docsy helps you create and serve a well-organized, navigable technical documentation set, it frees you up to create and maintain great reliable, comprehensive content that your users can enjoy and trust. {{% /blocks/section %}} -{{% blocks/section type="section" color="primary" %}} +{{% blocks/section color="primary" %}} ## What's next for Docsy? Docsy is an open source project and we love getting patches and contributions to make Docsy and its docs even better. We hope to continue to make improvements to the theme along with the Docsy community. @@ -130,8 +129,5 @@ Docsy is an open source project and we love getting patches and contributions to Visit our [Issues](https://github.com/google/docsy/issues) to see what we're currently working on. If there's something you'd like to see in Docsy, please create an issue yourself - or assign yourself an issue if you'd like to fix or add something! See our [contribution guidelines](/docs/contribution-guidelines/) for more information. You can find out how to update your site to the latest version of Docsy in [Keeping the theme up to date](/docs/updating/). + {{% /blocks/section %}} - - - - diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index ef6ec3dd25..2b99b71d52 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -97,7 +97,7 @@ The example below shows a section wrapping 3 feature sections. ```go-html-template -{{}} +{{}} {{%/* blocks/feature icon="fa-lightbulb" title="Fastest OS **on the planet**!" */%}} The new **TechOS** operating system is an open source project. It is a new project, but with grand ambitions. Please follow this space for updates! @@ -113,9 +113,9 @@ For announcement of latest features etc. | Parameter | Default | Description | | ---------------- |------------| ------------| -| height | | See above. -| color | | See above. -| type | | Specify "section" if you want a general container, omit this parameter if you want this section to contain a horizontal row of features. +| `height` | | See above. +| `color` | | See above. +| `type` | | Specify "container" (the default) if you want a general container, or "row" if the section will contain columns -- which must be immediate children. ### blocks/feature diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index 54ef664b12..b95d4ce432 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -40,6 +40,9 @@ languages: markup: goldmark: + parser: + attribute: + block: true renderer: unsafe: true highlight: From 1d192e35fe4e5cb9c95ce37af875669eee124df2 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 9 Mar 2023 16:02:07 -0500 Subject: [PATCH 68/76] [BSv5] Factor out Docy's table style and set max-width (#1474) --- assets/scss/_boxes.scss | 4 +--- assets/scss/_content.scss | 19 ++++++++----------- assets/scss/_table.scss | 5 +++++ assets/scss/main.scss | 1 + 4 files changed, 15 insertions(+), 14 deletions(-) create mode 100644 assets/scss/_table.scss diff --git a/assets/scss/_boxes.scss b/assets/scss/_boxes.scss index f55c6c080b..9d2d49fd6f 100644 --- a/assets/scss/_boxes.scss +++ b/assets/scss/_boxes.scss @@ -82,9 +82,7 @@ padding-right: 5vw; } table { - @extend .table; - @extend .table-striped; - @extend .table-responsive; + @extend .td-table; } } diff --git a/assets/scss/_content.scss b/assets/scss/_content.scss index 0d60885077..4a75992d5f 100644 --- a/assets/scss/_content.scss +++ b/assets/scss/_content.scss @@ -41,11 +41,7 @@ } table { - @extend .table-striped; - - @extend .table-responsive; - - @extend .table; + @extend .td-table; } blockquote { @@ -64,18 +60,19 @@ font-weight: $font-weight-bold; } - > pre, + .footnotes, + > .alert, > .highlight, > .lead, + > .td-table, + > blockquote, + > dl dd, > h1, > h2, - > ul, > ol, > p, - > blockquote, - > dl dd, - .footnotes, - > .alert { + > pre, + > ul { @extend .td-max-width-on-larger-screens; } diff --git a/assets/scss/_table.scss b/assets/scss/_table.scss new file mode 100644 index 0000000000..1f6167d888 --- /dev/null +++ b/assets/scss/_table.scss @@ -0,0 +1,5 @@ +.td-table { + @extend .table; + @extend .table-responsive; + @extend .table-striped; +} diff --git a/assets/scss/main.scss b/assets/scss/main.scss index d8038c3770..cbad7f3678 100644 --- a/assets/scss/main.scss +++ b/assets/scss/main.scss @@ -19,6 +19,7 @@ $display1-size: null !default; @import "support/utilities"; @import "colors"; +@import "table"; @import "boxes"; @import "blog"; @import "code"; From b1ad3a772d1502b144b2cdadc9775154c12a9983 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Mar 2023 14:30:37 -0500 Subject: [PATCH 69/76] [BSv5] Set tables to display:block and explain why (#1477) --- assets/scss/_table.scss | 8 ++- .../en/docs/adding-content/lookandfeel.md | 49 +++++++++++++++++++ 2 files changed, 55 insertions(+), 2 deletions(-) diff --git a/assets/scss/_table.scss b/assets/scss/_table.scss index 1f6167d888..eadba6ab65 100644 --- a/assets/scss/_table.scss +++ b/assets/scss/_table.scss @@ -1,5 +1,9 @@ -.td-table { +.td-table:not(.td-initial) { @extend .table; - @extend .table-responsive; @extend .table-striped; + @extend .table-responsive; + + // The following is needed for tables to be responsive. + // For details, see the https://docsy.dev/docs/adding-content/lookandfeel/#tables + display: block; } diff --git a/userguide/content/en/docs/adding-content/lookandfeel.md b/userguide/content/en/docs/adding-content/lookandfeel.md index fec0cd4e03..699724b0e4 100644 --- a/userguide/content/en/docs/adding-content/lookandfeel.md +++ b/userguide/content/en/docs/adding-content/lookandfeel.md @@ -239,6 +239,55 @@ of the following: [wordmark]: https://en.wikipedia.org/wiki/Wordmark [your logo]: /docs/adding-content/iconsimages/#add-your-logo +## Tables + +Docsy applies the following styles to all tables, through the class `.td-table`: + +- [Bootstrap table][] styles: + - `.table` + - `.table-striped` + - `.table-responsive` +- `display: block`, which is necessary for tables to be responsive. + +This styling configuration gives you responsive tables using Markdown only, +without the need to wrap the table in a `
`. It does, however, mean that all your tables have `display` +set to `block`. If you don't want this, you can create your own custom styles for tables. + +{{% alert title="Note" %}} + +Our table styling goes against the [Bootstrap recommendation to _wrap_ +tables][wrap-tables] with `.table-responsive` — however, we think letting +users create responsive tables with just Markdown table syntax is more +convenient. + +[wrap-tables]: https://getbootstrap.com/docs/5.3/content/tables/#responsive-tables + +{{% /alert %}} + +To render a table without Docsy styling, apply the `.td-initial` class to the +table. From the resulting `` style base, it is easier to apply your own +custom styles (rather than trying to undo Docsy table styling), as is +illustrated in the following example: + +```markdown +| Shape | Number of sides | +| -------- | --------------- | +| Triangle | 3 | +| Square | 4 | +{.td-initial .my-dark-table-style} +``` + +The example above uses [Markdown attribute][] syntax, and might render like this: + +| Shape | Number of sides | +| -------- | --------------- | +| Triangle | 3 | +| Square | 4 | +{.td-initial .table .table-dark} + +[Bootstrap table]: https://getbootstrap.com/docs/5.3/content/tables/ +[Markdown attribute]: https://discourse.gohugo.io/t/markdown-attributes/41783 + ## Customizing templates ### Add code to head or before body end From 096aa627f07765e52fcad2831e1e477e24f89780 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 10 Mar 2023 18:54:08 -0500 Subject: [PATCH 70/76] [BSv5] Fix position of blog's RSS button (#1480) --- assets/scss/_blog.scss | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/assets/scss/_blog.scss b/assets/scss/_blog.scss index 0cbf655002..70f2b95979 100644 --- a/assets/scss/_blog.scss +++ b/assets/scss/_blog.scss @@ -4,9 +4,7 @@ @extend .btn-lg; @extend .-bg-orange; - position: absolute; - right: 1rem; - z-index: 22; + float: right; display: none; @extend .d-lg-block; From 79e44b8ddf2984a31cc7164b9eb91d63c473d216 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Fri, 3 Mar 2023 14:59:31 -0600 Subject: [PATCH 71/76] Shortcodes: Update readfile to throw compile error Update readfile shortcode to throw a compile error when the file is not found. Currenlty the shortcode prints a message on the UI, which presents a problem when refactoring a docs site. A UI message requires visual conformation and is easy to miss when moving or renaming directories. --- layouts/shortcodes/readfile.html | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html index ce05aef322..7921a1c7c4 100644 --- a/layouts/shortcodes/readfile.html +++ b/layouts/shortcodes/readfile.html @@ -34,8 +34,4 @@ {{ else }} {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}} {{ end }} -{{ else }} - -

The file {{ $.Scratch.Get "filepath" }} was not found.

- -{{ end }} +{{ else }}{{- errorf "File not found: %s %s" ($.Scratch.Get "filepath") .Position -}}{{ end }} From 29e1decb870f38915ee8ca27f7414ff3cb5286e7 Mon Sep 17 00:00:00 2001 From: Aimee Ukasick Date: Tue, 18 Apr 2023 13:04:01 -0500 Subject: [PATCH 72/76] add suggestions; update userguide --- layouts/shortcodes/readfile.html | 10 +++++++--- .../en/docs/adding-content/shortcodes/index.md | 18 ++++++++++++++++-- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/layouts/shortcodes/readfile.html b/layouts/shortcodes/readfile.html index 7921a1c7c4..0a9b5a95ae 100644 --- a/layouts/shortcodes/readfile.html +++ b/layouts/shortcodes/readfile.html @@ -24,8 +24,8 @@ {{ end }} -{{/* If the file exists, read it and highlight it if it's code. Throw an error -if the file is not found */}} +{{/* If the file exists, read it and highlight it if it's code. +Throw a compile error or print an error on the page if the file is not found */}} {{ if fileExists ($.Scratch.Get "filepath") }} {{ if eq (.Get "code") "true" }} @@ -34,4 +34,8 @@ {{ else }} {{- $.Scratch.Get "filepath" | os.ReadFile | .Page.RenderString | safeHTML -}} {{ end }} -{{ else }}{{- errorf "File not found: %s %s" ($.Scratch.Get "filepath") .Position -}}{{ end }} +{{ else if eq (.Get "draft") "true" }} + +

The file {{ $.Scratch.Get "filepath" }} was not found.

+ +{{ else }}{{- errorf "Shortcode %q: file %q not found at %s" .Name ($.Scratch.Get "filepath") .Position -}}{{ end }} diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index 2b99b71d52..c3a2cb16a7 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -679,14 +679,28 @@ under the parent file's working directory are supported. For files outside the current working directory you can use an absolute path starting with `/`. The root directory is the `/content` folder. - - | Parameter | Default | Description | | ---------------- |------------| ------------| | file | | Path of external file| | code | false | Boolean value. If `true` the contents is treated as code| | lang | plain text | Programming language | +### Error reporting + +If the shortcode can't find the specified file, the shortcode throws a compile error. + +In the following example, Hugo throws a compile error if it can't find `includes/deploy.yml`: + +```go-html-template +{{}} +``` + +Alternately, Hugo you can display a message on the rendered page instead of throwing a compile error. Add `draft="true"` as a parameter. For example: + +```go-html-template +{{}} +``` + ## Conditional text The `conditional-text` shortcode allows you to show or hide parts of your content depending on the value of the `buildCondition` parameter set in your configuration file. This can be useful if you are generating different builds from the same source, for example, using a different product name. This shortcode helps you handle the minor differences between these builds. From dbec2962f400da4f01d12f39d57981364525b5a4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 4 May 2023 10:25:54 -0400 Subject: [PATCH 73/76] Drop mycplus.com iframe from Shortcode page (#1475) --- .../en/docs/adding-content/shortcodes/index.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index c3a2cb16a7..ef7de03c97 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -120,11 +120,9 @@ For announcement of latest features etc. ### blocks/feature ```go-html-template - {{%/* blocks/feature icon="fa-brands fa-github" title="Contributions welcome!" url="https://github.com/gohugoio/hugo" */%}} We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions workflow on **GitHub**. New users are always welcome! {{%/* /blocks/feature */%}} - ``` | Parameter | Default | Description | @@ -139,7 +137,6 @@ We do a [Pull Request](https://github.com/gohugoio/hugo/pulls) contributions wor The **blocks/link-down** shortcode creates a navigation link down to the next section. It's meant to be used in combination with the other blocks shortcodes. ```go-html-template -
{{}}
@@ -179,7 +176,6 @@ The **pageinfo** shortcode creates a text box that you can use to add banner inf {{%/* pageinfo color="primary" */%}} This is placeholder content. {{%/* /pageinfo */%}} - ``` Renders to: @@ -197,7 +193,6 @@ This is placeholder content The **imgproc** shortcode finds an image in the current [Page Bundle](/docs/adding-content/content/#page-bundles) and scales it given a set of processing instructions. - ```go-html-template {{}} Norway Spruce Picea abies shoot with foliage buds. @@ -388,9 +383,6 @@ object HelloWorld extends App { println("Hello world!") } {{< /tab >}} -{{< tab header="Reference" right=true text=true >}} -{{< iframe src="https://www.mycplus.com/featured-articles/hello-world-programs-in-300-programming-languages" >}} -{{< /tab >}} {{< /tabpane >}} The Docsy template provides two shortcodes `tabpane` and `tab` that let you easily create tabbed panes. To see how to use them, have a look at the following code block, which renders to a right aligned pane with one disabled and three active tabs: @@ -606,7 +598,6 @@ Check system compatibility before proceeding. `sudo sh install.sh` 1. Test that your installation was successfully completed. - ``` You can import this section into another document: @@ -615,7 +606,6 @@ You can import this section into another document: The following section explains how to install the database: {{%/* readfile "installation.md" */%}} - ``` This is rendered as if the instructions were in the parent document. Hugo @@ -650,7 +640,6 @@ To create a new pipeline, follow the next steps: {{}} 1. Apply the file to your cluster `kubectl apply config.yaml` - ``` This code automatically reads the content of `includes/config.yaml` and inserts it @@ -660,11 +649,11 @@ into the document. The rendered text looks like this: To create a new pipeline, follow the next steps: -1. Create a configuration file `config.yaml`: +1. Create a configuration file `config.yaml`: {{< readfile file="includes/config.yaml" code="true" lang="yaml" >}} -1. Apply the file to your cluster `kubectl apply config.yaml` +1. Apply the file to your cluster `kubectl apply config.yaml` --- From e977fe3015ba9bc53ef61cb2efc510e77a5e41bf Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 4 May 2023 16:48:37 +0200 Subject: [PATCH 74/76] [BSv5] Adapt cardpane shortcode --- CHANGELOG.md | 8 ++ assets/scss/shortcodes/cards-pane.scss | 3 +- layouts/shortcodes/card-code.html | 28 +++---- layouts/shortcodes/card.html | 76 +++++++++---------- layouts/shortcodes/cardpane.html | 4 +- .../docs/adding-content/shortcodes/index.md | 69 +++++++++-------- 6 files changed, 95 insertions(+), 93 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index babb0b1d2a..ba0afe7810 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,6 +30,14 @@ For a list of issues targeted for the next release, see the [23Q1][] milestone. - `blocks/section`: **default** and accepted values of the `type` argument have changed! For details see [blocks/section] ([#1472]). +- **[Adaptation of shortcodes for diplay of cards (#1376)][1376]: + - shortcode `cardpane`: renamed CSS class `td-card-deck` to `td-card-group`. + - shortcode `card`, `card-code`: markup of inner content (html/markdown) + now depends on the syntax of the calling shortcode, not on extension + of page file any more [#906][906]. + - shortcode `card-code` is now deprecated, use shortcode `card` with named + parameter `code=true` instead. + **Other changes**: - Non-breaking changes that result from the Bootstrap v5 upgrade: diff --git a/assets/scss/shortcodes/cards-pane.scss b/assets/scss/shortcodes/cards-pane.scss index bea122b8ab..f3af98751c 100644 --- a/assets/scss/shortcodes/cards-pane.scss +++ b/assets/scss/shortcodes/cards-pane.scss @@ -1,4 +1,4 @@ -.td-card-deck.card-deck { +.td-card-group.card-group { @extend .td-max-width-on-larger-screens; } @@ -8,6 +8,7 @@ .highlight { border: none; + margin: 0; } } diff --git a/layouts/shortcodes/card-code.html b/layouts/shortcodes/card-code.html index a7c5465d83..28908907f8 100644 --- a/layouts/shortcodes/card-code.html +++ b/layouts/shortcodes/card-code.html @@ -1,20 +1,16 @@ -
- {{ $lang := "" }} - {{ with $.Get "lang" }} - {{ $lang = $.Get "lang" }} - {{ end }} - {{ $highlight := "" }} - {{ with $.Get "highlight" }} - {{ $highlight = $.Get "highlight" }} - {{ end }} - {{- with $.Get "header" -}} +{{ warnf `shortcode 'card-code' is deprecated: use shortcode 'card' with named parameter 'code=true' instead.` -}} +{{ $lang := default "" ($.Get "lang") -}} +{{ $highlight := default "" ($.Get "highlight") -}} + +
+ {{ with $.Get "header" -}}
- {{- $.Get "header" | markdownify -}} + {{ . | markdownify -}}
- {{end}} -
- {{ with $.Inner }} - {{- highlight $.Inner $lang $highlight -}} - {{ end }} + {{ end -}} +
+ {{ with $.Inner -}} + {{ highlight . $lang $highlight -}} + {{ end -}}
diff --git a/layouts/shortcodes/card.html b/layouts/shortcodes/card.html index f0558133b7..74138a1f3c 100644 --- a/layouts/shortcodes/card.html +++ b/layouts/shortcodes/card.html @@ -1,49 +1,47 @@ -
- {{ with $.Get "header" }} -
- {{ if eq $.Page.File.Ext "md" }} - {{ $.Get "header" | markdownify }} - {{ else }} - {{ $.Get "header" | htmlUnescape | safeHTML }} - {{ end }} +{{/* Check parameter type */ -}} +{{ $code := false -}} +{{ with .Get "code" -}} + {{ $type := printf "%T" . -}} + {{ if ne $type "bool" -}} + {{ errorf `shortcode 'card': boolean value expected for parameter 'code', but got %s` $type -}} + {{ else }} + {{ $code = . -}} + {{ end -}} +{{ end -}} + +{{ $lang := default "" (.Get "lang") -}} +{{ $highlight := default "" (.Get "highlight") -}} + +
+{{ with $.Get "header" -}} +
+ {{ . | markdownify }}
- {{ end }} -
- {{ with $.Get "title" }} +{{ end -}} +
+ {{ with $.Get "title" -}}
- {{ if eq $.Page.File.Ext "md" }} - {{ $.Get "title" | markdownify }} - {{ else }} - {{ $.Get "title" | htmlUnescape | safeHTML }} - {{ end }} + {{ . | markdownify -}}
- {{ end }} - {{ with $.Get "subtitle" }} -
- {{ if eq $.Page.File.Ext "md" }} - {{ $.Get "subtitle" | markdownify }} - {{ else }} - {{ $.Get "subtitle" | htmlUnescape | safeHTML }} - {{ end }} + {{ end -}} + {{ with $.Get "subtitle" -}} +
+ {{ . | markdownify -}}
- {{ end }} - {{ with $.Inner }} + {{ end -}} + {{ with $.Inner -}} + {{ if $code -}} + {{ highlight . $lang $highlight -}} + {{ else -}}

- {{ if eq $.Page.File.Ext "md" }} - {{ $.Inner | markdownify }} - {{ else }} - {{ $.Inner | htmlUnescape | safeHTML }} - {{ end }} + {{ . -}}

- {{ end }} + {{ end -}} + {{ end -}}
- {{ with $.Get "footer" }} + {{ with $.Get "footer" -}}
- {{ if eq $.Page.File.Ext "md" }} - {{ $.Get "footer" | markdownify }} - {{ else }} - {{ $.Get "footer" | htmlUnescape | safeHTML }} - {{ end }} + {{ . | markdownify -}}
- {{ end }} + {{ end -}}
diff --git a/layouts/shortcodes/cardpane.html b/layouts/shortcodes/cardpane.html index 2617fdbaa2..caa3f8b66f 100644 --- a/layouts/shortcodes/cardpane.html +++ b/layouts/shortcodes/cardpane.html @@ -1,3 +1,3 @@ -
+
{{- .Inner -}} -
\ No newline at end of file +
diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index ef7de03c97..f2806ac3bf 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -417,7 +417,7 @@ This code translates to the right aligned tabbed pane below, showing a `Welcome! Herzlich willkommen! Flag Germany {{< /tab >}} - {{% tab header="Swahili" lang="sw" %}} + {{% tab header="Swahili" lang="sw" %}} ![Flag Tanzania](flags/tz.png) **Karibu sana!** {{% /tab %}} @@ -428,9 +428,9 @@ This code translates to the right aligned tabbed pane below, showing a `Welcome! Tabbed panes are implemented using two shortcodes: * The `tabpane` shortcode, which is the container element for the tabs. This shortcode can hold the optional named parameters `lang`, `highlight` and `right`. The value of the optional parameters `lang` and `highlight` are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code blocks of the individual tabs. Specify `right=true` if you want to right align your tabs. In case the header text of the tab equals the language used in the tab's code block (as in the first tabbed pane example above), you may specify `langEqualsHeader=true` in the surrounding `tabpane` shortcode. Then, the header text of the individual tab is automatically set as `lang` parameter of the respective tab. -* The various `tab` shortcodes represent the tabs you would like to show. Specify the named parameter `header` for each tab in order to set the header text of the tab. If the `header` parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like `{ tab "My header" }} … {{ /tab }}`. If your `tab` shortcode does not have any parameters, the header of the tab will default to `Tab n`. To split the panes into a left aligned and a right aligned tab group, specify `right=true` in the dividing tab. By giving `right=true` several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter `disabled=true`. For enabled tabs, there are two modes for content display, `code` representation and _textual_ representation: +* The various `tab` shortcodes represent the tabs you would like to show. Specify the named parameter `header` for each tab in order to set the header text of the tab. If the `header` parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like `{{< tab "My header" >}} … {{< /tab >}}`. If your `tab` shortcode does not have any parameters, the header of the tab will default to `Tab n`. To split the panes into a left aligned and a right aligned tab group, specify `right=true` in the dividing tab. By giving `right=true` several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter `disabled=true`. For enabled tabs, there are two modes for content display, `code` representation and _textual_ representation: * By default, the tab's content is rendered as `code block`. In order to get proper syntax highlighting, specify the named parameter `lang` --and optionally the parameter `highlight`-- for each tab. Parameters set in the parent `tabpane` shortcode will be overwritten. - * If the contents of your tabs should be rendered as text with different styles and with optional images, specify `text=true` as parameter of your `tabpane` (or your `tab`). If your content is markdown, use the percent sign `%` as outermost delimiter of your `tab` shortcode, your markup should look like `{{%/* tab */%}}`Your \*\*markdown\*\* content`{{%/* /tab */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{}}`Your <b>HTML</b> content`{{}}`. + * If the contents of your tabs should be rendered as text with different styles and with optional images, specify `text=true` as parameter of your `tabpane` (or your `tab`). If your content is markdown, use the percent sign `%` as outermost delimiter of your `tab` shortcode, your markup should look like `{{%/* tab */%}}Your **markdown** content{{%/* /tab */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{}}Your HTML content{{}}`. {{% alert title="Info" %}} By default, the language of the selected tab is stored and preserved between different browser sessions. If the content length within your tabs differs greatly, this may lead to unwanted scrolling when switching between tabs. To disable this unwanted behaviour, specify `persistLang=false` within your `tabpane` shortcode. @@ -440,30 +440,29 @@ By default, the language of the selected tab is stored and preserved between dif When authoring content, it's sometimes very useful to put similar text blocks or code fragments on card like elements, which can be optionally presented side by side. Let's showcase this feature with the following sample card group which shows the first four Presidents of the United States: -{{< cardpane >}} -{{< card header="**George Washington**" title="\*1732     †1799" subtitle="**President:** 1789 – 1797" footer="![SignatureGeorgeWashington](https://upload.wikimedia.org/wikipedia/commons/thumb/2/2e/George_Washington_signature.svg/320px-George_Washington_signature.svg.png 'Signature George Washington')">}} +{{% cardpane %}} +{{% card header="**George Washington**" title="\*1732     †1799" subtitle="**President:** 1789 – 1797" footer="![SignatureGeorgeWashington](https://upload.wikimedia.org/wikipedia/commons/thumb/2/2e/George_Washington_signature.svg/320px-George_Washington_signature.svg.png 'Signature George Washington')" %}} ![PortraitGeorgeWashington](https://upload.wikimedia.org/wikipedia/commons/thumb/b/b6/Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg/633px-Gilbert_Stuart_Williamstown_Portrait_of_George_Washington.jpg "Portrait George Washington") -{{< /card >}} -{{< card header="**John Adams**" title="\* 1735     † 1826" subtitle="**President:** 1797 – 1801" footer="![SignatureJohnAdams](https://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/John_Adams_Sig_2.svg/320px-John_Adams_Sig_2.svg.png 'Signature John Adams')" >}} +{{% /card %}} +{{% card header="**John Adams**" title="\* 1735     † 1826" subtitle="**President:** 1797 – 1801" footer="![SignatureJohnAdams](https://upload.wikimedia.org/wikipedia/commons/thumb/e/e8/John_Adams_Sig_2.svg/320px-John_Adams_Sig_2.svg.png 'Signature John Adams')" %}} ![PortraitJohnAdams](https://upload.wikimedia.org/wikipedia/commons/thumb/f/ff/Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg/633px-Gilbert_Stuart%2C_John_Adams%2C_c._1800-1815%2C_NGA_42933.jpg "Portrait John Adams") -{{< /card >}} -{{< card header="**Thomas Jefferson**" title="\* 1743     † 1826" subtitle="**President:** 1801 – 1809" footer="![SignatureThomasJefferson](https://upload.wikimedia.org/wikipedia/commons/thumb/0/0d/Thomas_Jefferson_Signature.svg/320px-Thomas_Jefferson_Signature.svg.png 'Signature Thomas Jefferson')" >}} +{{% /card %}} +{{% card header="**Thomas Jefferson**" title="\* 1743     † 1826" subtitle="**President:** 1801 – 1809" footer="![SignatureThomasJefferson](https://upload.wikimedia.org/wikipedia/commons/thumb/0/0d/Thomas_Jefferson_Signature.svg/320px-Thomas_Jefferson_Signature.svg.png 'Signature Thomas Jefferson')" %}} ![PortraitThomasJefferson](https://upload.wikimedia.org/wikipedia/commons/thumb/b/b1/Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg/390px-Official_Presidential_portrait_of_Thomas_Jefferson_%28by_Rembrandt_Peale%2C_1800%29%28cropped%29.jpg "Portrait Thomas Jefferson") -{{< /card >}} -{{< card header="**James Madison**" title="\* 1751     † 1836" subtitle="**President:** 1809 – 1817" footer="![SignatureJamesMadison](https://upload.wikimedia.org/wikipedia/commons/thumb/3/39/James_Madison_sig.svg/320px-James_Madison_sig.svg.png 'Signature James Madison')" >}} +{{% /card %}} +{{% card header="**James Madison**" title="\* 1751     † 1836" subtitle="**President:** 1809 – 1817" footer="![SignatureJamesMadison](https://upload.wikimedia.org/wikipedia/commons/thumb/3/39/James_Madison_sig.svg/320px-James_Madison_sig.svg.png 'Signature James Madison')" %}} ![PortraitJamesMadison](https://upload.wikimedia.org/wikipedia/commons/thumb/2/20/James_Madison%28cropped%29%28c%29.jpg/393px-James_Madison%28cropped%29%28c%29.jpg "Portrait James Madison") -{{< /card >}} -{{< /cardpane >}} +{{% /card %}} +{{% /cardpane %}} Docsy supports creating such card panes via different shortcodes: * The `cardpane` shortcode which is the container element for the various cards to be presented. -* The `card` shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A `card` shortcode can hold text, images or any other arbitrary kind of markdown or HTML markup as content. If your content is programming code, you are advised to make use of the `card-code` shortcode, a special kind of card with code-highlighting and other optional features like line numbers, highlighting of certain lines, …. +* The `card` shortcodes, with each shortcode representing an individual card. While cards are often presented inside a card group, a single card may stand on its own, too. A `card` shortcode can hold programming code, text, images or any other arbitrary kind of markdown or HTML markup as content. In case of programming code, cards provide automatic code-highlighting and other optional features like line numbers, highlighting of certain lines, …. -### Shortcode `card` (for text, images, …) +### Shortcode `card`: textual content -As stated above, a card is coded using one of the shortcode `card` or `card-code`. -If your content is any kind of text other than programming code, use the universal `card`shortcode. The following code sample demonstrates how to code a card element: +Make use of the `card` shortcode to display a card. The following code sample demonstrates how to code a card element: ```go-html-template {{}} -{{< card header="**Imagine**" title="Artist and songwriter: John Lennon" subtitle="Co-writer: Yoko Ono" footer="![SignatureJohnLennon](https://upload.wikimedia.org/wikipedia/commons/thumb/5/51/Firma_de_John_Lennon.svg/320px-Firma_de_John_Lennon.svg.png 'Signature John Lennon')">}} +{{% cardpane %}} +{{< card header="**Imagine**" title="Artist and songwriter: John Lennon" subtitle="Co-writer: Yoko Ono" footer="![SignatureJohnLennon](https://upload.wikimedia.org/wikipedia/commons/thumb/5/51/Firma_de_John_Lennon.svg/320px-Firma_de_John_Lennon.svg.png 'Signature John Lennon')" >}} Imagine there's no heaven, It's easy if you try
No hell below us, above us only sky
Imagine all the people living for today… @@ -494,19 +493,19 @@ Imagine all the people sharing all the world… You may say I'm a dreamer, but I'm not the only one
I hope someday you'll join us and the world will live as one {{< /card >}} -{{< card header="**Header**: specified via named parameter `Header`" title="**Card title**: specified via named parameter `title`" subtitle="**Card subtitle**: specified via named parameter `subtitle`" footer="**Footer**: specified via named parameter `footer`" >}} - **Content**: inner content of the shortcode, this may be formatted text, images, videos, … . If the extension of your page file equals `.md`, markdown format is expected, otherwise, your content will be treated as plain HTML. -{{< /card >}} -{{< /cardpane >}} +{{% card header="**Header**: specified via named parameter `Header`" title="**Card title**: specified via named parameter `title`" subtitle="**Card subtitle**: specified via named parameter `subtitle`" footer="**Footer**: specified via named parameter `footer`" %}} + **Content**: inner content of the shortcode, this may be plain text or formatted text, images, videos, … . If your content is markdown, use the percent sign `%` as outermost delimiter of your `card` shortcode, your markup should look like `{{%/* card */%}}Your **markdown** content{{%/* /card */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{}}Your HTML content{{}}` +{{% /card %}} +{{% /cardpane %}} While the main content of the card is taken from the inner markup of the `card` shortcode, the optional elements `footer`, `header`, `title`, and `subtitle` are all specified as named parameters of the shortcode. -### Shortcode `card-code` (for programming code) +### Shortcode `card`: programming code -In case you want to display programming code on your card, a special shortcode `card-code` is provided for this purpose. The following sample demonstrates how to code a card element with the famous `Hello world!`application coded in C: +If you want to display programming code on your card, set the named parameter `code` of the card to `true`. The following sample demonstrates how to code a card element with the famous `Hello world!` application coded in C: ```go-html-template -{{}} +{{}} #include #include @@ -515,12 +514,12 @@ int main(void) puts("Hello World!"); return EXIT_SUCCESS; } -{{}} +{{}} ``` This code translates to the card shown below: -{{< card-code header="**C**" lang="C" highlight="" >}} +{{< card code=true header="**C**" lang="C" highlight="" >}} #include #include @@ -529,9 +528,9 @@ int main(void) puts("Hello World!"); return EXIT_SUCCESS; } -{{< /card-code >}} +{{< /card >}} -
The `card-code` shortcode can optionally hold the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code block presented on the card. +
If called with parameter `code=true`, the `card` shortcode can optionally hold the named parameters `lang` and/or `highlight`. The values of these optional parameters are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code block presented on the card. ### Card groups @@ -555,18 +554,18 @@ The general markup of a card group resembles closely the markup of a tabbed pane Contrary to tabs, cards are presented side by side, however. This is especially useful it you want to compare different programming techniques (traditional vs. modern) on two cards, like demonstrated in the example above: {{< cardpane >}} -{{< card-code header="**Java 5**" >}} +{{< card code=true header="**Java 5**" >}} File[] hiddenFiles = new File("directory_name") .listFiles(new FileFilter() { public boolean accept(File file) { return file.isHidden(); } }); -{{< /card-code >}} -{{< card-code header="**Java 8, Lambda expression**" >}} +{{< /card >}} +{{< card code=true header="**Java 8, Lambda expression**" >}} File[] hiddenFiles = new File("directory_name") .listFiles(File::isHidden); -{{< /card-code >}} +{{< /card >}} {{< /cardpane >}} ## Include external files @@ -662,7 +661,7 @@ You must use `{{}}` delimiters for the code highlighting to work correctly. {{% /alert %}} -The "file" parameter is the relative path to the file. Only relative paths +The `file` parameter is the relative path to the file. Only relative paths under the parent file's working directory are supported. For files outside the current working directory you can use an absolute path From 15bb85789703132d3d347d6f78bc5c062b792300 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 4 May 2023 20:08:02 +0200 Subject: [PATCH 75/76] Tabpane shortcodes: improved reporting of warnings and errors (#1478) --- layouts/shortcodes/blocks/lead.html | 2 +- layouts/shortcodes/imgproc.html | 28 +++++++++---------- layouts/shortcodes/tab.html | 13 +++++---- layouts/shortcodes/tabpane.html | 12 ++++---- .../docs/adding-content/shortcodes/index.md | 2 +- 5 files changed, 30 insertions(+), 27 deletions(-) diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html index 6c12d62037..5afe34c647 100644 --- a/layouts/shortcodes/blocks/lead.html +++ b/layouts/shortcodes/blocks/lead.html @@ -2,7 +2,7 @@ {{ $height := .Get "height" | default "auto" -}} {{ with .Get "height" -}} {{ if not ( or ( eq . "auto" ) ( eq . "min" ) ( eq . "med" ) ( eq . "max" ) ( eq . "full" ) ) -}} - {{ errorf "shortcode 'lead': parameter height is '%s', must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}} + {{ errorf "shortcode 'lead': parameter height is %q, must be one of 'auto', 'min', 'med', 'max' or 'full'." . -}} {{ end -}} {{ end -}} diff --git a/layouts/shortcodes/imgproc.html b/layouts/shortcodes/imgproc.html index 6c5a211f90..318f0f2404 100644 --- a/layouts/shortcodes/imgproc.html +++ b/layouts/shortcodes/imgproc.html @@ -1,17 +1,17 @@ -{{ $original := .Page.Resources.GetMatch (printf "**%s*" (.Get 0)) }} -{{ $command := .Get 1 }} -{{ $options := .Get 2 }} -{{ if eq $command "Fit"}} -{{ .Scratch.Set "image" ($original.Fit $options) }} -{{ else if eq $command "Resize"}} -{{ .Scratch.Set "image" ($original.Resize $options) }} -{{ else if eq $command "Fill"}} -{{ .Scratch.Set "image" ($original.Fill $options) }} -{{ else if eq $command "Crop"}} -{{ .Scratch.Set "image" ($original.Crop $options) }} -{{ else }} -{{ errorf "Invalid image processing command: Must be one of Fit, Fill, Crop or Resize."}} -{{ end }} +{{ $original := .Page.Resources.GetMatch (printf "**%s*" (.Get 0)) -}} +{{ $command := .Get 1 -}} +{{ $options := .Get 2 -}} +{{ if eq $command "Fit" -}} +{{ .Scratch.Set "image" ($original.Fit $options) -}} +{{ else if eq $command "Resize" -}} +{{ .Scratch.Set "image" ($original.Resize $options) -}} +{{ else if eq $command "Fill" -}} +{{ .Scratch.Set "image" ($original.Fill $options) -}} +{{ else if eq $command "Crop" -}} +{{ .Scratch.Set "image" ($original.Crop $options) -}} +{{ else -}} +{{ errorf "Invalid image processing command %q: must be one of Fit, Fill, Crop or Resize." $command -}} +{{ end -}} {{ $image := .Scratch.Get "image" }}
diff --git a/layouts/shortcodes/tab.html b/layouts/shortcodes/tab.html index 8ec7e09d5e..d13e0338e3 100644 --- a/layouts/shortcodes/tab.html +++ b/layouts/shortcodes/tab.html @@ -1,8 +1,11 @@ {{- /* 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" -}} + {{ if ne $.Parent.Name "tabpane" -}} + {{ errorf "Found shortcode %q enclosed inside a %q block, must be enclosed inside a %q block. Error position: %s" $.Name $.Parent.Name "tabpane" $.Position -}} {{ end -}} +{{ else -}} + {{ errorf "shortcode %q must be enclosed inside a %q block, but no parent block was found. Error position: %s" $.Name "tabpane" $.Position -}} {{ end -}} {{ $header := "Tab" -}} @@ -23,19 +26,19 @@ {{ end -}} {{ with $.Get "text" -}} {{ if ne ( printf "%T" . ) "bool" -}} - {{ errorf "shortcode tab: parameter 'text' must be either true or false" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "text" (printf "%T" .) $.Position -}} {{ 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" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "right" (printf "%T" .) $.Position -}} {{ 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" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "disabled" (printf "%T" .) $.Position -}} {{ end -}} {{ $tab = merge $tab (dict "disabled" ($.Get "disabled")) -}} {{ end -}} diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html index d22a59a193..c553383db0 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/shortcodes/tabpane.html @@ -1,25 +1,25 @@ {{/* Check parameter types */ -}} {{ with .Get "langEqualsHeader" -}} - {{ if ne ( printf "%T" . ) "bool" -}} - {{ errorf "shortcode tabpane: parameter 'langEqualsHeader' must be either true or false" -}} + {{ if ne ( printf "%T" . ) "bool" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "langEqualsHeader" (printf "%T" .) $.Position -}} {{ end -}} {{ end -}} {{ with .Get "text" -}} {{ if ne ( printf "%T" . ) "bool" -}} - {{ errorf "shortcode tabpane: parameter 'text' must be either true or false" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "text" (printf "%T" .) $.Position -}} {{ end -}} {{ end -}} {{ with .Get "persistLang" -}} {{ if ne ( printf "%T" . ) "bool" -}} - {{ errorf "shortcode tabpane: parameter 'persistLang' must be either true or false" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "persistLang" (printf "%T" .) $.Position -}} {{ end -}} {{ end -}} {{ with .Get "right" -}} {{ if ne ( printf "%T" . ) "bool" -}} - {{ errorf "shortcode tabpane: parameter 'right' must be either true or false" -}} + {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "right" (printf "%T" .) $.Position -}} {{ end -}} {{ end -}} @@ -101,7 +101,7 @@ {{ if $duplicate -}} - {{ warnf "Tabpane on page '%s': duplicate language '%s' detected, disabling persistance of language to avoid multiple tab display." .Page.RelPermalink $duplicateLang -}} + {{ warnf "Shortcode %q: duplicate language %q detected, disabling persistance of language to avoid multiple tab display. Position: %s" $.Name $duplicateLang $.Position -}} {{ end -}} {{ $duplicate = false -}} {{ $langs = slice -}} diff --git a/userguide/content/en/docs/adding-content/shortcodes/index.md b/userguide/content/en/docs/adding-content/shortcodes/index.md index f2806ac3bf..e8e9f35093 100644 --- a/userguide/content/en/docs/adding-content/shortcodes/index.md +++ b/userguide/content/en/docs/adding-content/shortcodes/index.md @@ -428,7 +428,7 @@ This code translates to the right aligned tabbed pane below, showing a `Welcome! Tabbed panes are implemented using two shortcodes: * The `tabpane` shortcode, which is the container element for the tabs. This shortcode can hold the optional named parameters `lang`, `highlight` and `right`. The value of the optional parameters `lang` and `highlight` are passed on as second `LANG` and third `OPTIONS` arguments to Hugo's built-in [`highlight`](https://gohugo.io/functions/highlight/) function which is used to render the code blocks of the individual tabs. Specify `right=true` if you want to right align your tabs. In case the header text of the tab equals the language used in the tab's code block (as in the first tabbed pane example above), you may specify `langEqualsHeader=true` in the surrounding `tabpane` shortcode. Then, the header text of the individual tab is automatically set as `lang` parameter of the respective tab. -* The various `tab` shortcodes represent the tabs you would like to show. Specify the named parameter `header` for each tab in order to set the header text of the tab. If the `header` parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like `{{< tab "My header" >}} … {{< /tab >}}`. If your `tab` shortcode does not have any parameters, the header of the tab will default to `Tab n`. To split the panes into a left aligned and a right aligned tab group, specify `right=true` in the dividing tab. By giving `right=true` several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter `disabled=true`. For enabled tabs, there are two modes for content display, `code` representation and _textual_ representation: +* The various `tab` shortcodes represent the tabs you would like to show. Specify the named parameter `header` for each tab in order to set the header text of the tab. If the `header` parameter is the only parameter inside your tab shortcode, you can specify the header as unnamed parameter, something like `{{}} … {{}}`. If your `tab` shortcode does not have any parameters, the header of the tab will default to `Tab n`. To split the panes into a left aligned and a right aligned tab group, specify `right=true` in the dividing tab. By giving `right=true` several times, you can even render multiple tab groups. You can disable a tab by specifying the parameter `disabled=true`. For enabled tabs, there are two modes for content display, `code` representation and _textual_ representation: * By default, the tab's content is rendered as `code block`. In order to get proper syntax highlighting, specify the named parameter `lang` --and optionally the parameter `highlight`-- for each tab. Parameters set in the parent `tabpane` shortcode will be overwritten. * If the contents of your tabs should be rendered as text with different styles and with optional images, specify `text=true` as parameter of your `tabpane` (or your `tab`). If your content is markdown, use the percent sign `%` as outermost delimiter of your `tab` shortcode, your markup should look like `{{%/* tab */%}}Your **markdown** content{{%/* /tab */%}}`. In case of HTML content, use square brackets `<>` as outermost delimiters: `{{}}Your HTML content{{}}`. From 13db293f5217aa92b15aa7514bee34a43f241039 Mon Sep 17 00:00:00 2001 From: Razon Yang Date: Sun, 7 May 2023 02:17:21 +0800 Subject: [PATCH 76/76] module: ignore Bootstrap config (#1509) --- dependencies/config.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/dependencies/config.toml b/dependencies/config.toml index 3ba31f38f9..a701110574 100644 --- a/dependencies/config.toml +++ b/dependencies/config.toml @@ -25,6 +25,7 @@ _merge = "deep" [[module.imports]] path = "github.com/twbs/bootstrap" disable = false + ignoreConfig = true [[module.imports.mounts]] source = "scss" target = "assets/vendor/bootstrap/scss"