Merge branch 'main' into copyright-year

google · Jul 5, 2023 · 70f92d6 · 70f92d6
2 parents ce7c170 + ff188ef
commit 70f92d6
Show file tree

Hide file tree

Showing 3 changed files with 88 additions and 58 deletions.
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # Docsy
 
+## 🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use official Docsy [releases].
+
 Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets,
 providing simple navigation, site structure, and more.
 
@@ -12,52 +14,54 @@ The following are basic prerequisites for using Docsy in your site:
 
 - Install a recent release of the Hugo "extended" version. If you install from
   the [Hugo release page](https://github.com/gohugoio/hugo/releases), make sure
-  you download the `_extended` version which supports SCSS.
+  you download the `extended` version, which supports SCSS.
 
 - Install `PostCSS` so that the site build can create the final CSS assets. You
   can install it locally by running the following commands from the root
   directory of your project:
 
-  ```console
-  $ npm install --save-dev autoprefixer
-  $ npm install --save-dev postcss-cli
+  ```sh
+  npm install --save-dev autoprefixer
+  npm install --save-dev postcss-cli
   ```
-
-  Starting in [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md),
+
+  Starting in
+  [version 8 of `postcss-cli`](https://github.com/postcss/postcss-cli/blob/master/CHANGELOG.md),
   you must also separately install `postcss`:
 
-  ```bash
+  ```sh
   npm install -D postcss
   ```
-
-Any additional prerequisites depend on the [installation option](https://www.docsy.dev/docs/get-started/#installation-options)
-you choose. We recommend using Docsy as a Hugo module, which requires that
-you have the `go` language installed in addition to Hugo and PostCSS.
 
-For complete prerequisites and instructions, see our [Get started guides](https://www.docsy.dev/docs/get-started/).
+Any additional prerequisites depend on the
+[installation option](https://www.docsy.dev/docs/get-started/#installation-options)
+you choose. We recommend using Docsy as a Hugo module, which requires that you
+have the `go` language installed in addition to Hugo and PostCSS.
+
+For complete prerequisites and instructions, see our
+[Get started guides](https://www.docsy.dev/docs/get-started/).
 
 ## Example and usage
 
-You can find an example project that uses Docsy in the [Docsy Example Project
-repo](https://github.com/google/docsy-example).The Docsy Example Project is
-hosted at [example.docsy.dev](https://example.docsy.dev). For
+You can find an example project that uses Docsy in the
+[Docsy Example Project repo](https://github.com/google/docsy-example).The Docsy
+Example Project is hosted at [example.docsy.dev](https://example.docsy.dev). For
 real-life examples of sites that use Docsy (and their source repos), see our
 [Examples](https://www.docsy.dev/docs/examples/) page.
 
 To use the Docsy theme for your own site:
 
-- (Recommended) Use the [example
-  project](https://github.com/google/docsy-example), which includes the Docsy
-  theme as a Hugo module, as a template to create your project. You can customize
-  this pre-configured basic site into your own Docsy themed site. [Learn
-  more...](https://github.com/google/docsy-example)
+- (Recommended) Use the
+  [example project](https://github.com/google/docsy-example), which includes the
+  Docsy theme as a Hugo module, as a template to create your project. You can
+  customize this pre-configured basic site into your own Docsy themed site.
+  [Learn more...](https://github.com/google/docsy-example)
 
-- Add Docsy to your existing Hugo site. You can
-  add Docsy as a Hugo module, as a Git submodule, or clone the Docsy theme into your
-  project.
+- Add Docsy to your existing Hugo site. You can add Docsy as a Hugo module, as a
+  Git submodule, or clone the Docsy theme into your project.
 
-See the [Get started guides](https://www.docsy.dev/docs/get-started/)
-for details about the various usage options.
+See the [Get started guides](https://www.docsy.dev/docs/get-started/) for
+details about the various usage options.
 
 ## Documentation
 
@@ -70,27 +74,27 @@ Alternatively you can use Hugo to generate and serve a local copy of the guide
 (also useful for testing local theme changes), making sure you have installed
 all the prerequisites listed above:
 
-```console
-$ git clone --depth 1 https://github.com/google/docsy.git
-$ cd docsy/userguide/
-$ npm install
-$ npm run serve
+```sh
+git clone --depth 1 https://github.com/google/docsy.git
+cd docsy/userguide/
+npm install
+npm run serve
 ```
 
 ## Contributing ![GitHub](https://img.shields.io/github/contributors/google/docsy)
 
 Please read
-[CONTRIBUTING.md](https://github.com/google/docsy/blob/main/CONTRIBUTING.md)
-for details on our code of conduct, and the process for submitting pull requests
-to us. See also the list of
+[CONTRIBUTING.md](https://github.com/google/docsy/blob/main/CONTRIBUTING.md) for
+details on our code of conduct, and the process for submitting pull requests to
+us. See also the list of
 [contributors](https://github.com/google/docsy/graphs/contributors) who
 participated in this project.
 
 ## License ![GitHub](https://img.shields.io/github/license/google/docsy)
 
 This project is licensed under the Apache License 2.0 - see the
-[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for
-details
+[LICENSE.md](https://github.com/google/docsy/blob/main/LICENSE) file for details
 
-[Deploys]: https://app.netlify.com/sites/docsydocs/deploys
-[Netlify]: https://netlify.com
+[deploys]: https://app.netlify.com/sites/docsydocs/deploys
+[netlify]: https://netlify.com
+[releases]: https://github.com/google/docsy/releases
diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html
@@ -11,9 +11,20 @@
   {{ end -}}
 {{ end -}}
 
-{{ with .Get "persistLang" -}}
-  {{ if ne ( printf "%T" . ) "bool" -}}
-    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "persistLang" (printf "%T" .) $.Position  -}}
+{{ $_persistLang := .Get "persistLang" -}}
+{{ if and (ne $_persistLang nil) (ne $_persistLang "") -}}
+  {{ if ne ( printf "%T" $_persistLang ) "bool" -}}
+    {{ errorf "Shortcode %q: boolean value expected for parameter %q, but got %s. Error position: %s" $.Name "persistLang" (printf "%T" $_persistLang) $.Position  -}}
+  {{ else -}}
+    {{ warnf "Shortcode %q parameter `persistLang` is deprecated, use `persist` instead: %s" $.Name $.Position  -}}
+  {{ end -}}
+{{ end -}}
+
+{{ $_persist := .Get "persist" -}}
+{{ with $_persist -}}
+  {{ $matched := findRE "^(header|lang|none)$" . -}}
+  {{ if not $matched -}}
+    {{ errorf "Shortcode %q: parameter %q should be one of 'header', 'lang', or 'none'; but got %s. Error position: %s" $.Name "persist" $_persist $.Position  -}}
   {{ end -}}
 {{ end -}}
 
@@ -28,15 +39,17 @@
 {{ $hloptionsPane := default "" ($.Get "highlight") -}}
 {{ $textPane := default false ($.Get "text") -}}
 {{ $langEqualsHeader := default false ($.Get "langEqualsHeader") -}}
-{{ $persistLang := default true ($.Get "persistLang") -}}
+{{ $deprecatedPersistLang := $_persistLang | default true -}}
+{{ $persistKeyKind := $_persist | default (cond (eq $langPane "") "lang" "header") -}}
+{{ $persistTab := and $deprecatedPersistLang (ne $persistKeyKind "none") -}}
 {{ $rightPane := default false ($.Get "right") -}}
 {{ $activeSet := false -}}
 {{- /* Scratchpad gets populated through call to .Inner */ -}}
 {{- .Inner -}}
 
-{{ $langs := slice -}}
+{{ $persistKeyList := slice -}}
 {{ $duplicate := false -}}
-{{ $duplicateLang := "" -}}
+{{ $duplicateKey := "" -}}
 
 {{ $Ordinal := $.Ordinal -}}
 {{ if ge hugo.Version "0.93.0" -}}
@@ -62,14 +75,21 @@
       {{ $lang = . -}}
     {{ end -}}
 
-    {{/* Check for duplicate languages */ -}}
-    {{ if and $persistLang (not $duplicate) -}}
-      {{ if and (not $disabled) (ne $lang "") -}}
-        {{ $langs = $langs | append $lang -}}
-      {{ end -}}
-      {{ if ne $langs (uniq $langs) -}}
+    {{ $persistKey := "" -}}
+    {{ if eq $persistKeyKind "lang" -}}
+      {{ $persistKey = $lang -}}
+    {{ else if eq $persistKeyKind "header" -}}
+      {{ $persistKey = $element.header -}}
+    {{ end -}}
+
+    {{/* Check for duplicate tab-persistence keys */ -}}
+    {{ if and $persistTab $persistKey -}}
+      {{ if in $persistKey $persistKeyList -}}
         {{ $duplicate = true -}}
-        {{ $duplicateLang = $lang -}}
+        {{ $duplicateKey = $persistKey -}}
+        {{ $persistTab = false -}}
+      {{ else -}}
+        {{ $persistKeyList = $persistKeyList | append $persistKey -}}
       {{ end -}}
     {{ end -}}
 
@@ -78,16 +98,23 @@
       {{ $rightpush = . -}}
     {{ end -}}
 
-    {{/* Replace space and +, not valid for css selectors */ -}}
-    {{ $lang := replaceRE "[\\s+]" "-" $lang -}}
+    {{/* Replace by "-" all chars that are not valid in a CSS class name: */ -}}
+    {{ $persistKey = replaceRE "[^a-zA-Z0-9_-]" "-" $persistKey | lower -}}
     <li class="nav-item{{ if $rightpush }} ms-auto{{ end -}}">
       {{/* Generate the IDs for the <a> and the <div> elements */ -}}
       {{ $tabid := printf "tabs-%02v-%v-tab" $Ordinal $index | anchorize -}}
       {{ $entryid := printf "tabs-%02v-%v" $Ordinal $index | anchorize -}}
 
-      <button class="nav-link{{ if and ( not $activeSet ) ( not $disabled ) }} active{{ end }}{{ if $disabled }} disabled{{ end }}{{ if ne $lang "" }}{{ if and $persistLang (not $duplicate) }} persistLang-{{- $lang -}}{{ end }}{{ end }}"
+      <button class="nav-link
+        {{- if and ( not $activeSet ) ( not $disabled ) }} active{{ end -}}
+        {{ if $disabled }} disabled{{ end -}}
+        {{ with $persistKey -}}
+          {{ if $persistTab }} persistLang-{{ . }}{{ end -}}
+        {{ end }}"
           id="{{ $tabid }}" data-bs-toggle="tab" data-bs-target="#{{ $entryid }}" role="tab"
-          {{ if ne $lang "" }}{{ if and $persistLang (not $duplicate) }}onclick="persistLang({{ $lang }});"{{ end }}{{ end -}}
+          {{ with $persistKey -}}
+            {{ if $persistTab }}onclick="persistLang({{ . }});" {{ end -}}
+          {{ end -}}
           aria-controls="{{- $entryid -}}" aria-selected="{{- cond ( and ( not $activeSet ) ( not $disabled ) ) "true" "false" -}}">
         {{ index . "header" | markdownify }}
       </button>
@@ -101,10 +128,9 @@
 </ul>
 
 {{ if $duplicate -}}
-  {{ warnf "Shortcode %q: duplicate language %q detected, disabling persistance of language to avoid multiple tab display. Position: %s" $.Name $duplicateLang $.Position -}}
+  {{ warnf "Shortcode %q: duplicate tab-persistence key %q detected, disabling persistance to avoid multiple tab display. Position: %s" $.Name $duplicateKey $.Position -}}
 {{ end -}}
-{{ $duplicate = false -}}
-{{ $langs = slice -}}
+
 {{ $activeSet = false -}}
 
 {{/* Tab panes */ -}}

diff --git a/package.json b/package.json
@@ -28,7 +28,7 @@
     "bootstrap": "5.2.3"
   },
   "devDependencies": {
-    "hugo-extended": "0.113.0"
+    "hugo-extended": "0.115.1"
   },
   "engines": {
     "node": ">=18"