From b3ff908b672d9a2718a0029f243918bd361cd855 Mon Sep 17 00:00:00 2001 From: Erin McKean Date: Thu, 18 May 2023 10:35:03 -0700 Subject: [PATCH 01/71] Update CONTRIBUTING.md (#1511) Co-authored-by: LisaFC --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0f8a216700..82ccce057c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,6 +29,10 @@ information on using pull requests. This project follows [Google's Open Source Community Guidelines](https://opensource.google.com/conduct/). +## Student contributions + +Docsy welcomes contributions from students. However, we cannot guarantee that PRs will be merged within any specific timeframe. We ask that instructors *not* create assignments requiring students to have PRs merged into the project. We will not merge PRs solely to satisfy any class assignments. + ## How to contribute See the [contribution guidelines][] in the Docsy user guide. From 9f3dbbd5c719bc99011210db9496b57d73fa6aac Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 25 May 2023 18:55:22 +0200 Subject: [PATCH 02/71] User guide: fix warning about deprecated language config (#1519) --- userguide/hugo.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/userguide/hugo.yaml b/userguide/hugo.yaml index b95d4ce432..4c05b16069 100644 --- a/userguide/hugo.yaml +++ b/userguide/hugo.yaml @@ -34,9 +34,10 @@ services: languages: en: title: Docsy - description: Docsy does docs languageName: English weight: 1 + params: + description: Docsy does docs markup: goldmark: From 454b6f1419a8c070cda045201f25534e7149b030 Mon Sep 17 00:00:00 2001 From: Yann Soubeyrand Date: Thu, 25 May 2023 21:23:41 +0200 Subject: [PATCH 03/71] [BSv5] fix horizontal scrollbar issues (#1502) --- layouts/community/list.html | 2 +- layouts/shortcodes/blocks/cover.html | 2 +- layouts/shortcodes/blocks/lead.html | 2 +- layouts/shortcodes/blocks/section.html | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/layouts/community/list.html b/layouts/community/list.html index 08e949e414..4ad718f168 100644 --- a/layouts/community/list.html +++ b/layouts/community/list.html @@ -4,7 +4,7 @@
-
+

{{ T "community_join" . }}

diff --git a/layouts/shortcodes/blocks/cover.html b/layouts/shortcodes/blocks/cover.html index 36790be4b0..a055c399f9 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 }} diff --git a/layouts/shortcodes/blocks/lead.html b/layouts/shortcodes/blocks/lead.html index 5afe34c647..4c0582533c 100644 --- a/layouts/shortcodes/blocks/lead.html +++ b/layouts/shortcodes/blocks/lead.html @@ -8,7 +8,7 @@
-
+
{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} diff --git a/layouts/shortcodes/blocks/section.html b/layouts/shortcodes/blocks/section.html index fbe8f8c7ec..29f2e79e06 100644 --- a/layouts/shortcodes/blocks/section.html +++ b/layouts/shortcodes/blocks/section.html @@ -4,7 +4,7 @@
-
+
{{/* Do NOT remove this comment! It ends the HTML block above. See https://spec.commonmark.org/0.30/#html-blocks, 7. */}} {{ .Inner -}} From acca3182f2abd468b3769772dfb736b47f90f5f4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 25 May 2023 18:13:20 -0400 Subject: [PATCH 04/71] [BSv5] Fix RSS button style (#1521) --- assets/scss/_blog.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/scss/_blog.scss b/assets/scss/_blog.scss index 70f2b95979..c2ade693c7 100644 --- a/assets/scss/_blog.scss +++ b/assets/scss/_blog.scss @@ -1,8 +1,8 @@ .td-blog { .td-rss-button { @extend .btn; + @extend .btn-info; @extend .btn-lg; - @extend .-bg-orange; float: right; From f22a70ec566ecdcfb267e1792115e96f7ed16ade Mon Sep 17 00:00:00 2001 From: Yann Soubeyrand Date: Fri, 26 May 2023 17:05:06 +0200 Subject: [PATCH 05/71] [BSv5] fix main container height (#1501) --- assets/scss/_main-container.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/scss/_main-container.scss b/assets/scss/_main-container.scss index f64592b01b..131a1b1549 100644 --- a/assets/scss/_main-container.scss +++ b/assets/scss/_main-container.scss @@ -2,7 +2,7 @@ .td-outer { display: flex; flex-direction: column; - height: 100vh; + min-height: 100vh; } // The outer page container for the default base template. From 4813275e57e5706dd59325f107e69cae0a0173b6 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 26 May 2023 13:06:23 -0400 Subject: [PATCH 06/71] [BSv5] Footer: drop flex-shrink tweak + other adjustments (#1523) --- CHANGELOG.md | 20 ++++++++++++-------- assets/scss/_variables.scss | 4 ++++ layouts/partials/footer.html | 8 ++++---- 3 files changed, 20 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba0afe7810..4ef4f984dd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,17 +29,19 @@ For a list of issues targeted for the next release, see the [23Q1][] milestone. - Dropped support for pre-Hugo-0.54.x behavior of `{{% %}}`. ([#939]) - `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. + - **Card shortcodes** ([#1376])]: + - Renamed CSS class `td-card-deck` to `td-card-group`. + - `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]. + - `card-code` is deprecated; use `card` with named parameter `code=true` + instead. **Other changes**: +- `$list-inline-padding` is increased in support of footer icons ([#1523]). If + this global adjustment is a problem for your project, let us know and we can + contextualize the adjustment to the footer. - Non-breaking changes that result from the Bootstrap v5 upgrade: - Draw.io diagram edit button: replaced custom colors by BS's outline primary. @@ -47,8 +49,10 @@ For a list of issues targeted for the next release, see the [23Q1][] milestone. [#906]: https://github.com/google/docsy/issues/906 [#939]: https://github.com/google/docsy/issues/939 [#1369]: https://github.com/google/docsy/issues/1369 +[#1376]: https://github.com/google/docsy/issues/1369 [#1442]: https://github.com/google/docsy/issues/1442 [#1472]: https://github.com/google/docsy/issues/1472 +[#1523]: https://github.com/google/docsy/pull/1523 [blocks/section]: https://www.docsy.dev/docs/adding-content/shortcodes/#blockssection [bsv5mig]: https://getbootstrap.com/docs/5.2/migration/ diff --git a/assets/scss/_variables.scss b/assets/scss/_variables.scss index 89d42e17e9..4f02e2b659 100644 --- a/assets/scss/_variables.scss +++ b/assets/scss/_variables.scss @@ -87,3 +87,7 @@ $pagination-disabled-color: $gray-300 !default; // TODO: consider using BS defau $navbar-dark-color: rgba($white, 0.75) !default; // TODO: consider moving into UG SCSS $navbar-dark-hover-color: rgba($white, 0.5) !default; // TODO: consider moving into UG SCSS + +// Footer + +$list-inline-padding: $spacer; diff --git a/layouts/partials/footer.html b/layouts/partials/footer.html index 5ee524fd1e..4d6f3df70f 100644 --- a/layouts/partials/footer.html +++ b/layouts/partials/footer.html @@ -1,7 +1,7 @@ {{ $links := .Site.Params.links -}} -
From a640e98d760ff141e0e690b4bef09f31aacd1a49 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 27 Jul 2023 03:10:51 +0200 Subject: [PATCH 61/71] css: Support dartsass as transpiler (#1598) --- assets/scss/support/_bootstrap_vers_test.scss | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/assets/scss/support/_bootstrap_vers_test.scss b/assets/scss/support/_bootstrap_vers_test.scss index c5c0f25356..c65647acb8 100644 --- a/assets/scss/support/_bootstrap_vers_test.scss +++ b/assets/scss/support/_bootstrap_vers_test.scss @@ -1,8 +1,8 @@ $enable-important-utilities: null !default; @if $enable-important-utilities == null { - @error " - Docsy requires Bootstrap v5, but the v5 variable - $enable-important-utilities isn't defined. - Did you forget to update Docsy dependencies? + @error "\ + Docsy requires Bootstrap v5, but the v5 variable \ + $enable-important-utilities isn't defined. \ + Did you forget to update Docsy dependencies?\ "; } From f76bf243bdd407d498eecc0c6bbc511bf6167d8a Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 26 Jul 2023 21:05:52 -0400 Subject: [PATCH 62/71] Allow link-color to be set by projects --- assets/scss/_variables.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/scss/_variables.scss b/assets/scss/_variables.scss index 4f02e2b659..0dd43d8e2a 100644 --- a/assets/scss/_variables.scss +++ b/assets/scss/_variables.scss @@ -34,7 +34,7 @@ $td-sidebar-border-color: $border-color !default; $td-box-colors: $dark, $primary, $secondary, $info, $white, $gray-600, $success, $warning, $dark, $danger, $primary, $secondary, $info !default; -$link-color: $blue-500; +$link-color: $blue-500 !default; $link-decoration: none !default; $link-shade-percentage: 30% !default; From 0b204744e761b6a3fc5ed7d0a48bd2e15e60817d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jes=C3=BAs=20Garc=C3=ADa=20Crespo?= Date: Thu, 27 Jul 2023 19:22:58 +0200 Subject: [PATCH 63/71] Fix whitespace cleanup syntax issue (#1626) --- layouts/swagger/list.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/swagger/list.html b/layouts/swagger/list.html index d988ee8966..9d67295e3b 100644 --- a/layouts/swagger/list.html +++ b/layouts/swagger/list.html @@ -5,7 +5,7 @@

{{ .Title }}

{{ partial "taxonomy_terms_article_wrapper.html" . -}} {{ if (and (not .Params.hide_readingtime) (.Site.Params.ui.readingtime.enable)) -}} - {{ partial "reading-time.html" .- }} + {{ partial "reading-time.html" . -}} {{ end -}}
{{ .Content }} From b7252104e2d9a89291e7f493c0eb0a90c721b45c Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 27 Jul 2023 22:25:19 +0200 Subject: [PATCH 64/71] README.md: add badges at top of page (#1623) --- README.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ff2e78953e..4b008ebdc3 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # Docsy +[![Project status: active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) +[![Project releases](https://img.shields.io/github/release/google/docsy)](https://github.com/google/docsy/releases) +[![Project build Status](https://badges.netlify.com/api/docsydocs.svg?branch=master)](https://app.netlify.com/sites/docsydocs/deploys) +[![Project contributors](https://img.shields.io/github/contributors/google/docsy)](https://github.com/google/docsy/graphs/contributors) +[![Project license](https://img.shields.io/github/license/google/docsy)](https://github.com/google/docsy/blob/main/LICENSE) + ## 🚧 WARNING 🚧 : `main` is under development and potentially unstable! Use official Docsy [releases]. Docsy is a [Hugo](https://gohugo.io) theme for technical documentation sets, @@ -81,7 +87,7 @@ npm install npm run serve ``` -## Contributing ![GitHub](https://img.shields.io/github/contributors/google/docsy) +## Contributing Please read [CONTRIBUTING.md](https://github.com/google/docsy/blob/main/CONTRIBUTING.md) for @@ -90,7 +96,7 @@ 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) +## License 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 From ab1f1d0257a09cce2fd820665b1b4900bf38921c Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 27 Jul 2023 22:28:00 +0200 Subject: [PATCH 65/71] Feedback questions: add localization (#1615) --- i18n/de.toml | 10 ++++++++++ i18n/en.toml | 11 ++++++++++- layouts/partials/feedback.html | 8 ++++---- 3 files changed, 24 insertions(+), 5 deletions(-) diff --git a/i18n/de.toml b/i18n/de.toml index 665eedf3b3..d64e7b166c 100644 --- a/i18n/de.toml +++ b/i18n/de.toml @@ -79,3 +79,13 @@ other = "Wenn Du aktiv beteiligen und einen Beitrag zu {{ .Site.Title }} leisten other = "Wie Du selbst zu {{ .Site.Title }} beitragen kannst, kannst Du nachlesen in unseren" [community_guideline] other = "Richtlinien für Beiträge" + +# Feedback +[feedback_title] +other = "Rückmeldung" +[feedback_question] +other = "War diese Seite hilfreich?" +[feedback_positive] +other = "Ja" +[feedback_negative] +other = "Nein" diff --git a/i18n/en.toml b/i18n/en.toml index 476b1cd67b..dcb78102c9 100644 --- a/i18n/en.toml +++ b/i18n/en.toml @@ -27,7 +27,6 @@ other = "All Rights Reserved" [footer_privacy_policy] other = "Privacy Policy" - # Post (blog, articles etc.) [post_byline_by] other = "By" @@ -79,3 +78,13 @@ other = "If you want to get more involved by contributing to {{ .Site.Title }}, other = "You can find out how to contribute to {{ .Site.Title }} in our" [community_guideline] other = "Contribution Guidelines" + +# Feedback +[feedback_title] +other = "Feedback" +[feedback_question] +other = "Was this page helpful?" +[feedback_positive] +other = "Yes" +[feedback_negative] +other = "No" diff --git a/layouts/partials/feedback.html b/layouts/partials/feedback.html index 20f5e46774..239e530b59 100644 --- a/layouts/partials/feedback.html +++ b/layouts/partials/feedback.html @@ -14,10 +14,10 @@ }
- - - - + + + + From 9741e0749e8093fb92bc91e8aad486e4c347a965 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 2 Aug 2023 16:08:43 -0400 Subject: [PATCH 66/71] tabpane width fix (#1639) --- assets/scss/shortcodes/tabbed-pane.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/scss/shortcodes/tabbed-pane.scss b/assets/scss/shortcodes/tabbed-pane.scss index 65096aee6e..1c0d81825b 100644 --- a/assets/scss/shortcodes/tabbed-pane.scss +++ b/assets/scss/shortcodes/tabbed-pane.scss @@ -8,6 +8,7 @@ .tab-content { .tab-pane { + @extend .td-max-width-on-larger-screens; .highlight { margin: 0rem 0 0rem 0; border: none; @@ -15,7 +16,6 @@ } margin-top: 0rem; margin-bottom: 1.5rem; - max-width: 80%; 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); From 3f3172a190ac9b24aa5b9c695f62c3fee8273ac2 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 2 Aug 2023 16:10:44 -0400 Subject: [PATCH 67/71] tabpane: fix duplicate-key detection (#1638) --- layouts/shortcodes/tabpane.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html index ad58f413c7..7359da5b11 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/shortcodes/tabpane.html @@ -82,7 +82,7 @@ {{/* Check for duplicate tab-persistence keys */ -}} {{ if and $persistTab $persistKey -}} - {{ if in $persistKey $persistKeyList -}} + {{ if in $persistKeyList $persistKey -}} {{ $duplicate = true -}} {{ $duplicateKey = $persistKey -}} {{ $persistTab = false -}} From 71f4f30403a1f78dd9141b392674ebea13ab788f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 3 Aug 2023 13:25:02 -0400 Subject: [PATCH 68/71] User guide Print page: move tabs to separate pane to eliminate warning (#1642) --- userguide/content/en/docs/adding-content/print.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/userguide/content/en/docs/adding-content/print.md b/userguide/content/en/docs/adding-content/print.md index 101d84a48f..f830fe91c1 100644 --- a/userguide/content/en/docs/adding-content/print.md +++ b/userguide/content/en/docs/adding-content/print.md @@ -46,30 +46,33 @@ The site should then show a "Print entire section" link in the right hand naviga To disable showing the the table of contents in the printable view, set the `disable_toc` param to `true`, either in the page front matter, or in `hugo.toml`/`hugo.yaml`/`hugo.json`: -{{< tabpane >}} +{{< tabpane langEqualsHeader=true >}} {{< tab header="Front matter:" disabled=true />}} -{{< tab header="toml" lang="toml" >}} +{{< tab toml >}} +++ … disable_toc = true … +++ {{< /tab >}} -{{< tab header="yaml" lang="yaml" >}} +{{< tab yaml >}} --- … disable_toc: true … --- {{< /tab >}} -{{< tab header="json" lang="json" >}} +{{< tab json >}} { …, "disable_toc": true, … } {{< /tab >}} -{{< tab header="or config file:" disabled=true />}} +{{< /tabpane >}} + +{{< tabpane >}} +{{< tab header="Config file:" disabled=true />}} {{< tab header="hugo.toml" lang="toml" >}} [params.print] disable_toc = true From c171841fed0bcf9af4ddaa067aad3825ee69026e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 3 Aug 2023 13:53:48 -0400 Subject: [PATCH 69/71] New blog post: Upgrading to Docsy 0.7 & Bootstrap 5 (#1640) --- userguide/.htmltest.yml | 4 +- .../en/blog/2023/bootstrap-5-migration.md | 11 +- userguide/content/en/blog/2023/docsy-0.7.md | 180 ++++++++++++++++++ 3 files changed, 189 insertions(+), 6 deletions(-) create mode 100644 userguide/content/en/blog/2023/docsy-0.7.md diff --git a/userguide/.htmltest.yml b/userguide/.htmltest.yml index 4a67a2bae0..68c98992f0 100644 --- a/userguide/.htmltest.yml +++ b/userguide/.htmltest.yml @@ -5,4 +5,6 @@ IgnoreDirectoryMissingTrailingSlash: true # FIXME IgnoreDirs: [_print] # FIXME IgnoreEmptyHref: true # FIXME IgnoreInternalEmptyHash: true # FIXME -IgnoreInternalURLs: +IgnoreInternalURLs: # list of paths +IgnoreURLs: # list of regexs of paths or URLs to be ignored + - ^https://twitter.com/docsydocs$ diff --git a/userguide/content/en/blog/2023/bootstrap-5-migration.md b/userguide/content/en/blog/2023/bootstrap-5-migration.md index e66bdb2ca4..234cf9f2c8 100644 --- a/userguide/content/en/blog/2023/bootstrap-5-migration.md +++ b/userguide/content/en/blog/2023/bootstrap-5-migration.md @@ -9,7 +9,7 @@ author: > Docsy Steering Committee date: 2023-06-05 canonical_url: https://www.cncf.io/blog/2023/06/05/migrating-docsy-to-bootstrap-5/ -spelling: cSpell:ignore CNCF Chalin opentelemetry techdocs +cSpell:ignore: CNCF Chalin opentelemetry techdocs --- [Docsy](https://docsy.dev), and Docsy-based project websites ([including those @@ -85,8 +85,8 @@ This assumption wasn't apparent nor was it enforced in Bootstrap 4, consequently, some of Docsy's layouts failed to respect it. In [most cases](https://github.com/google/docsy/issues/1466), fixing violations consisted of simply wrapping a `.row`'s child element in a `.col`, but the -[Docsy footer](https://github.com/google/docsy/blob/v0.7.0/layouts/partials/footer.html) required a couple of -iterations to get right. +[Docsy footer](https://github.com/google/docsy/blob/v0.7.0/layouts/partials/footer.html) +required a couple of iterations to get right. My first footer adjustment reset [`flex-shrink`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink) to @@ -251,8 +251,8 @@ migration that didn't apply to Docsy since Docsy uses only the most trivial of forms. We'll have more to share about the OTel migration effort as well as general -project-specific migration advice in a followup blog post. In the meantime, I -hope that you have found parts of this technical article helpful for your own +project-specific migration advice in a [followup blog post][]. In the meantime, +I hope that you have found parts of this technical article helpful for your own migration efforts. [CNCF project](https://www.cncf.io/projects/) websites eager to migrate can send @@ -277,5 +277,6 @@ _A version of this article originally appeared as the [CNCF blog][] post [cncf blog]: https://www.cncf.io/blog/ [cncf-docsy]: https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/ +[followup blog post]: /blog/2023/docsy-0.7/ [original post]: {{% param canonical_url %}} diff --git a/userguide/content/en/blog/2023/docsy-0.7.md b/userguide/content/en/blog/2023/docsy-0.7.md new file mode 100644 index 0000000000..6c53bbec0a --- /dev/null +++ b/userguide/content/en/blog/2023/docsy-0.7.md @@ -0,0 +1,180 @@ +--- +title: Upgrading to Docsy 0.7 & Bootstrap 5 +linkTitle: Upgrading to Docsy 0.7 +description: A guide to upgrading to Docsy 0.7 and Bootstrap 5 with examples +author: > + [Patrice Chalin](https://github.com/chalin), [CNCF](https://www.cncf.io/) & + Docsy Steering Committee +date: 2023-08-03 +cSpell:ignore: CNCF Chalin opentelemetry namespacing docsy +--- + +Last June, Docsy celebrated a significant milestone with the release of version +[0.7.0](https://github.com/google/docsy/releases/tag/v0.7.0). This major upgrade +was the result of +[six months of meticulous work (#470)](https://github.com/google/docsy/issues/470) +focused on the migration to Bootstrap 5.2. For highlights and the rationale +behind that journey, see +[Migrating to Bootstrap 5.2](/blog/2023/bootstrap-5-migration/). + +This blog post is intended to help those who are upgrading to Docsy 0.7 and +Bootstrap 5, based on my Docsy 0.7 upgrade experiences, specifically related to +Bootstrap. The post starts with general guidance for Docsy-based projects +wishing to upgrade. Every project's migration experience will be unique, but +hopefully this post, and the two included case studies, will make your upgrade +process easier and faster. + +If you're here, you probably want to upgrade your Docsy-based project---so, +let's jump in! + +## Upgrading your project + +As was mentioned in the +[first post](/blog/2023/bootstrap-5-migration/#migrating-docsy-based-projects), +each project uses its own specific set of Bootstrap and Docsy features, so in +all likelihood, **your upgrade journey will be unique**. This section offers +some general guidance. + +### Upgrade Docsy + +If you haven't already, upgrade your project all the way up to Docsy 0.6 first. +Each release of Docsy can bring its own set of upgrade challenges that will vary +in size and effort depending on your project and the features it uses, as well +as how long it's been since your version of Docsy has been upgraded. You'll want +to get all pre-0.7 upgrade issues out of the way so that you can focus on +Bootstrap 5 issues. Once you are done, upgrade to the latest Docsy 0.7.x +release. + +### Address Bootstrap changes + +I recommend that you first walk through the Bootstrap 5.2 +[migration page](https://getbootstrap.com/docs/5.2/migration/) to get an +appreciation of the scope of the changes made to Bootstrap 5 relative to 4. +Identify the breaking changes to those Bootstrap features used by your project, +and address each individually. I mention a few breaking changes next and close +the section with a comment about what to do about the rest. + +Some Bootstrap changes will break your website's layout or functionality in +obvious ways. This is the case for the +[rename](https://getbootstrap.com/docs/5.2/migration/#utilities)[ of utility classes](https://getbootstrap.com/docs/5.2/migration/#utilities), +like `ml-1` and `pr-2`. Using regular-expression based search-and-replace over +your project's custom layouts or doc-page inline HTML is a good way to tackle +this. I've used regex like these: + +- Margin and padding: `\b([mp])[lr](-([0-5]|auto))\b` +- Left/right classes: `\b((float|border|rounded|text)-)(left|right)\b` + +If your project uses Bootstrap +[JavaScript plugins](https://getbootstrap.com/docs/5.2/migration/#javascript) +such as dropdowns, popovers, and tooltips, these will stop working until you +adjust data attribute names, which are now "namespaced" using the `data-bs` +prefix. For example, use `data-bs-toggle` instead of `data-toggle`. + +Other Bootstrap breaking changes will require more work to address, such as the +following that were mentioned in the +[TL;DR](/blog/2023/bootstrap-5-migration/#tldr) of the first post: + +- [Mixin `media-breakpoint-down()` argument shift](/blog/2023/bootstrap-5-migration/#mixin-media-breakpoint-down-argument-shift) +- [Grid `.row` and `.col` style changes](/blog/2023/bootstrap-5-migration/#grid-row-and-col-style-changes-are-breaking) +- [Import ordering of Bootstrap Sass files: functions first](/blog/2023/bootstrap-5-migration/#import-ordering-of-bootstrap-sass-files-functions-first) + +The Docsy blog layout used the `.media` class, which was +[dropped from Bootstrap 5](https://getbootstrap.com/docs/5.2/migration/#grid-updates). +This, and the +[`.row` and `.col` style changes](/blog/2023/bootstrap-5-migration/#grid-row-and-col-style-changes-are-breaking), +required a couple of iterated changes to the blog layouts, such as +[PR #1566](https://github.com/google/docsy/pull/1566). If your project +customizes blog layouts, then you'll want to walk through the updates carefully. +Otherwise, your project will get these updates automatically, without any +further required changes. + +Should you encounter a Bootstrap-5 breaking change affecting your project that +hasn't been mentioned above, you might find the opening comment of Docsy +[issue #470 · Upgrade to Bootstrap 5.2](https://github.com/google/docsy/issues/470) +useful: it lists 50 tasks, each addressing a distinct migration problem, +accompanied by notes or cross-referenced PRs that illustrate how each problem +was resolved. + +### Address Docsy-specific changes + +It is worth mentioning in passing some of the main Docsy 0.7 changes that aren't +related to Bootstrap, such as: + +- Default and accepted values of the `blocks/section`'s `type` argument have + changed ([#1472](https://github.com/google/docsy/issues/1472)) +- Pre-Hugo-0.54.x behavior of `{{%/* */%}}` is no longer supported + ([#939](https://github.com/google/docsy/issues/939)) +- [Hugo release](https://github.com/gohugoio/hugo/releases) 0.110.0 or later is + required + +For the complete list of changes, see the +[CHANGELOG at 0.7.0](https://github.com/google/docsy/blob/main/CHANGELOG.md#070). + +## Case studies + +Our two case study projects to illustrate the Docsy upgrade process are the +OpenTelemetry project and the Docsy example template repository. + +### opentelemetry.io + +[Several CNCF projects](https://www.cncf.io/blog/2023/01/19/fast-and-effective-tools-for-cncf-and-open-source-project-websites/) +use the Docsy theme, including [opentelemetry.io](https://opentelemetry.io/), +which I used as a Docsy pre-release test site. As suggested earlier, I first +upgraded Docsy from 0.4 to 0.6 +([opentelemetry.io issue #2419](https://github.com/open-telemetry/opentelemetry.io/issues/2419)). + +The upgrade to Docsy 0.7 went +[fairly smoothly](https://github.com/open-telemetry/opentelemetry.io/issues?q=label%3Adocsy+is%3Aclosed+closed%3A%3E2023-03-03). +In addition to addressing the "obvious changes" related to utility class renames +and data-attribute namespacing, the OTel website required these project-specific +changes: + +- [Breaking changes to](https://getbootstrap.com/docs/5.2/migration/#forms) + [forms](https://getbootstrap.com/docs/5.2/migration/#forms) required a + significant rework of the + [Registry](https://opentelemetry.io/ecosystem/registry/) form +- While the OTel website has no blog layout overrides, it made use of the + `.media` class (which was dropped) for registry entries. Flex styles were used + instead. + +That's it! To see how both of the above were resolved, see OTel +[PR #2490](https://github.com/open-telemetry/opentelemetry.io/pull/2490). + +### Docsy-example + +The [docsy-example](https://github.com/google/docsy-example) repository is a +[GitHub template](https://gitprotect.io/blog/how-to-use-github-repository-templates/) +that we suggest as a possible starting point for users looking to adopt +[Docsy for a new website](/docs/get-started/docsy-as-module/example-site-as-template/). +The example site features [multi-language support](/docs/language/), which had +an impact on the required upgrades. + +The example-site upgrade was even simpler than for the OTel website. The key +changes ([PR #221](https://github.com/google/docsy-example/pull/221)) were +mainly confined to the landing page of each natural language: + +- Utility-class renames, such as `.ml-*` and `.mr-*` to `.ms-*` and `.me-*` +- [blocks/section](/docs/adding-content/shortcodes/#blockssection) changes + ([PR #1472](https://github.com/google/docsy/pull/1472)): + - Language landing pages had to be renamed from `.html` to `.md` in support of + using blocks shortcodes to render markdown content + - Switched to `type="row"` for `blocks/section` elements that are rows (also + from [PR #220](https://github.com/google/docsy-example/pull/220)) + +That was it. + +## What next? + +If your project doesn't override any Docsy layouts, then your upgrade experience +should be relatively straightforward. Reviewing layout file changes, on the +other hand, always warrants special attention. + +With the tips shared here, I hope that your journey to Docsy 0.7 will be more +streamlined. Consider sharing your experiences by adding a comment to the +[discussion of 0.7.0](https://github.com/google/docsy/discussions/1555) or any +[later 0.7.x release](https://github.com/google/docsy/discussions/categories/announcement?discussions_q%3Dis%253Aopen%2Bcategory%253AAnnouncement). +Wishing you a successful upgrade journey! + +A special thanks to [Erin McKean](https://github.com/emckean) for detailed and +valuable feedback on this post, and to all who contributed to the 0.7.x releases +of Docsy and the Docsy example! From c7120659cc7bc6ffb3c2c636cf4627c1be18fa17 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 3 Aug 2023 16:19:30 -0400 Subject: [PATCH 70/71] Tabpane: improve key-kind default setting (#1643) --- layouts/shortcodes/tab.html | 12 +++---- layouts/shortcodes/tabpane.html | 57 +++++++++++++++++---------------- 2 files changed, 36 insertions(+), 33 deletions(-) diff --git a/layouts/shortcodes/tab.html b/layouts/shortcodes/tab.html index 3a9db6c171..561659649e 100644 --- a/layouts/shortcodes/tab.html +++ b/layouts/shortcodes/tab.html @@ -19,34 +19,34 @@ {{/* store all tab info in dict tab */ -}} {{ $tab := dict "header" $header -}} {{ with $.Get "lang" -}} - {{ $tab = merge $tab (dict "language" ($.Get "lang")) -}} + {{ $tab = merge $tab (dict "language" .) -}} {{ end -}} {{ with $.Get "highlight" -}} - {{ $tab = merge $tab (dict "highlight" ($.Get "highlight")) -}} + {{ $tab = merge $tab (dict "highlight" .) -}} {{ end -}} {{ with $.Get "text" -}} {{ if ne ( printf "%T" . ) "bool" -}} {{ 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")) -}} + {{ $tab = merge $tab (dict "text" .) -}} {{ end -}} {{ with $.Get "right" -}} {{ if ne ( printf "%T" . ) "bool" -}} {{ 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")) -}} + {{ $tab = merge $tab (dict "rightpush" .) -}} {{ end -}} {{ with $.Get "disabled" -}} {{ if ne ( printf "%T" . ) "bool" -}} {{ 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")) -}} + {{ $tab = merge $tab (dict "disabled" .) -}} {{ end -}} {{ with $.Inner -}} {{/* Trim any leading and trailing newlines from .Inner, this avoids spurious lines during syntax highlighting */ -}} - {{ $tab = merge $tab (dict "content" $.Inner) -}} + {{ $tab = merge $tab (dict "content" .) -}} {{ end -}} {{/* add dict tab to parent's scratchpad */ -}} diff --git a/layouts/shortcodes/tabpane.html b/layouts/shortcodes/tabpane.html index 7359da5b11..8b0156618d 100644 --- a/layouts/shortcodes/tabpane.html +++ b/layouts/shortcodes/tabpane.html @@ -43,8 +43,9 @@ {{ $textPane := default false ($.Get "text") -}} {{ $langEqualsHeader := default false ($.Get "langEqualsHeader") -}} {{ $deprecatedPersistLang := $_persistLang | default true -}} -{{ $persistKeyKind := $_persist | default (cond (eq $langPane "") "lang" "header") -}} -{{ $persistTab := and $deprecatedPersistLang (ne $persistKeyKind "disabled") -}} +{{ $persistKeyKind := $_persist + | default (cond (or $textPane (ne "" $langPane)) "header" "lang") -}} +{{ $persistTabpane := and $deprecatedPersistLang (ne $persistKeyKind "disabled") -}} {{ $rightPane := default false ($.Get "right") -}} {{ $activeSet := false -}} {{/* Scratchpad gets populated through call to .Inner */ -}} @@ -59,10 +60,7 @@
    {{ range $index, $element := $.Scratch.Get "tabs" -}} - {{ $disabled := false -}} - {{ with $element.disabled -}} - {{ $disabled = . -}} - {{ end -}} + {{ $enabled := not $element.disabled -}} {{ $lang := $langPane -}} {{ if $langEqualsHeader -}} @@ -74,14 +72,21 @@ {{ $persistKey := "" -}} {{ if eq $persistKeyKind "lang" -}} - {{ $persistKey = $lang -}} + {{ with $lang -}} + {{ $persistKey = . -}} + {{ else -}} + {{ with findRE "```(\\S+)" $element.content 1 -}} + {{ $persistKey = index . 1 -}} + {{ end -}} + {{ end -}} {{ else if eq $persistKeyKind "header" -}} {{ $persistKey = $element.header -}} {{ end -}} {{ $persistKey = $persistKey | lower -}} + {{ $persistTab := and $persistTabpane $persistKey $enabled -}} {{/* Check for duplicate tab-persistence keys */ -}} - {{ if and $persistTab $persistKey -}} + {{ if $persistTab -}} {{ if in $persistKeyList $persistKey -}} {{ $duplicate = true -}} {{ $duplicateKey = $persistKey -}} @@ -101,23 +106,23 @@ {{ $tabid := printf "tabs-%02v-%v-tab" $tabPaneOrdinal $index | anchorize -}} {{ $entryid := printf "tabs-%02v-%v" $tabPaneOrdinal $index | anchorize -}} + {{ $isActive := and $enabled (not $activeSet) -}} + - {{- if not $disabled -}} - {{ $activeSet = true -}} - {{ end -}} - - {{ end }} + {{- end }}
{{ if $duplicate -}} @@ -138,10 +143,7 @@ {{ $lang = . -}} {{ end -}} - {{ $disabled := false -}} - {{ with $element.disabled -}} - {{ $disabled = . -}} - {{ end -}} + {{ $enabled := not $element.disabled -}} {{ $hloptions := $hloptionsPane -}} {{ with $element.highlight -}} @@ -155,7 +157,12 @@ {{ $tabid := printf "tabs-%02v-%v-tab" $tabPaneOrdinal $index | anchorize -}} {{ $entryid := printf "tabs-%02v-%v" $tabPaneOrdinal $index | anchorize }} -
{{ if $text -}} {{ index . "content" -}} @@ -164,9 +171,5 @@ {{ end }}
- {{- if not $disabled -}} - {{ $activeSet = true -}} - {{ end -}} - - {{ end }} + {{- end }}
From d30b1c9468294c5d5327b63124490f3bdc758ceb Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Fri, 4 Aug 2023 14:52:47 +0200 Subject: [PATCH 71/71] Fix creation of new child page (#1644) --- layouts/partials/page-meta-links.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/page-meta-links.html b/layouts/partials/page-meta-links.html index 0e90cc93e9..74032e1b14 100644 --- a/layouts/partials/page-meta-links.html +++ b/layouts/partials/page-meta-links.html @@ -35,7 +35,7 @@ {{ $issuesURL := printf "%s/issues/new?title=%s" $gh_repo (safeURL $.Title ) -}} {{ $newPageStub := resources.Get "stubs/new-page-template.md" -}} {{ $newPageQS := querify "value" $newPageStub.Content "filename" "change-me.md" | safeURL -}} - {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo $gh_repo_path $newPageQS -}} + {{ $newPageURL := printf "%s/new/%s?%s" $gh_repo (path.Dir $gh_repo_path) $newPageQS -}} {{ T "post_view_this" }} {{ T "post_edit_this" }}