Skip to content

Bump Docsy to 0.3.x #48721

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
k8s-ci-robot merged 2 commits into from
Nov 20, 2024
Merged

Bump Docsy to 0.3.x #48721

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1ff8d96
Bump Docsy to v0.3.0
Oct 31, 2024
4d01654
Adapt sidebar navigation for newer Docsy
Nov 2, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitmodules
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
[submodule "themes/docsy"]
path = themes/docsy
url = https://github.com/google/docsy.git
branch = v0.2.0
branch = v0.3.0
[submodule "api-ref-generator"]
path = api-ref-generator
url = https://github.com/kubernetes-sigs/reference-docs
2 changes: 2 additions & 0 deletions hugo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,8 @@ url = "https://v1-27.docs.kubernetes.io"
[params.ui]
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = false
# Show this many levels in compact mode
ul_show = 3
Comment on lines 220 to +222
Copy link
Contributor

@chalin chalin Nov 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that setting ul_show makes sense when sidebar_menu_compact = false in line 220 (unless you have custom behavior in layouts/partials/sidebar-tree.html that differs from Docsy's).

Copy link
Contributor

@chalin chalin Nov 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just ran make build-preview with and without this change, and it makes no meaningful difference (there's this strange behavior of heading ID hashes differing by one or two hash characters, but that isn't related to this).

$ git diff | grep ^diff | wc -l                       
      24
$ git diff | grep ^diff | grep -v '_print' | wc -l    
       6
$ git diff | grep ^diff | grep -v '_print'        
diff --git a/es/docs/concepts/containers/runtime-class/index.html b/es/docs/concepts/containers/runtime-class/index.html
diff --git a/ja/docs/concepts/containers/runtime-class/index.html b/ja/docs/concepts/containers/runtime-class/index.html
diff --git a/ko/docs/concepts/containers/runtime-class/index.html b/ko/docs/concepts/containers/runtime-class/index.html
diff --git a/pt-br/docs/concepts/containers/runtime-class/index.html b/pt-br/docs/concepts/containers/runtime-class/index.html
diff --git a/ru/docs/concepts/containers/runtime-class/index.html b/ru/docs/concepts/containers/runtime-class/index.html
diff --git a/zh-cn/docs/concepts/containers/runtime-class/index.html b/zh-cn/docs/concepts/containers/runtime-class/index.html
$ git diff -I 'h4 id='
$

So I think that this delta can be dropped, right @sftim?

# Show expand/collapse icon for sidebar sections.
sidebar_menu_foldable = true
# https://github.com/gohugoio/hugo/issues/8918#issuecomment-903314696
Expand Down
76 changes: 29 additions & 47 deletions layouts/partials/sidebar-tree.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,36 +1,35 @@
{{/* 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 -}}
{{ $shouldDelayActive := ge (len .Site.Pages) $sidebarCacheLimit -}}
{{/* Always cache this partial; set the active class client side. */}}
{{ $shouldDelayActive := true }}
Comment on lines -1 to +2
Copy link
Contributor

@chalin chalin Nov 20, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sidebar_cache_limit is already set to 1 in the Hugo config, so effectively shouldDelayActive is true.

Why introduce a difference between the Docsy partial and this K8s override? My hope is that eventually K8s will have as few layout overrides as possible so that it can benefit from easier updates when new Docsy releases come out.

<div id="td-sidebar-menu" class="td-sidebar__inner{{ if $shouldDelayActive }} d-none{{ end }}">
{{ if not .Site.Params.ui.sidebar_search_disable -}}
<form class="td-sidebar__search d-flex align-items-center">
{{ partial "search-input.html" . }}
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
{{ else -}}
<div id="content-mobile">
<form class="td-sidebar__search d-flex align-items-center">
{{ partial "search-input.html" . }}
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-docs-nav" aria-expanded="false" aria-label="Toggle section navigation">
<button class="btn btn-link td-sidebar__toggle d-md-none p-0 ml-3 fas fa-bars" type="button" data-toggle="collapse" data-target="#td-section-nav" aria-controls="td-section-nav" aria-expanded="false" aria-label="Toggle section navigation">
</button>
</form>
</div>
<div id="content-desktop"></div>
{{ end -}}
<nav class="collapse td-sidebar-nav{{ if .Site.Params.ui.sidebar_menu_foldable }} foldable-nav{{ end }}" id="td-section-nav">
<!-- {{ if (gt (len .Site.Home.Translations) 0) }}
{{- if (and false (gt (len .Site.Home.Translations) 0) ) -}}
<div class="nav-item dropdown d-block d-lg-none">
{{ partial "navbar-lang-selector.html" . }}
</div>
{{ end }} -->
<!-- {{ $navRoot := cond (and (ne .Params.toc_root true) (eq .Site.Home.Type "docs")) .Site.Home .FirstSection }} -->
{{ 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 -}}
{{ $currentLang := .Site.Language -}}
{{ $currentLang := string .Site.Language -}}
<ul class="td-sidebar-nav__section pr-md-3 ul-{{ $ulNr }}">
{{ template "section-tree-nav-section" (dict "page" . "section" .FirstSection "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1) "currentLang" $currentLang) }}
{{ template "section-tree-nav-section" (dict "page" . "section" $navRoot "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" (add $ulShow 1) "currentLang" $currentLang) }}
</ul>
</nav>
</div>
Expand All @@ -42,9 +41,10 @@
{{ $treeRoot := cond (eq .ulNr 0) true false -}}
{{ $ulNr := .ulNr -}}
{{ $ulShow := .ulShow -}}
{{ $currentLang := .currentLang -}}
{{ $active := and (not $shouldDelayActive) (eq $s $p) -}}
{{ $activePath := and (not $shouldDelayActive) ($p.IsDescendant $s) -}}
{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}}
{{ $show := cond (or (lt $ulNr $ulShow) $activePath (and (not $shouldDelayActive) (eq $s.Parent $p.Parent)) (and (not $shouldDelayActive) (eq $s.Parent $p)) (not $p.Site.Params.ui.sidebar_menu_compact) (and (not $shouldDelayActive) ($p.IsDescendant $s.Parent))) true false -}}
{{ $mid := printf "m-%s" ($s.RelPermalink | anchorize) -}}
{{ $pages_tmp := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
{{/* We get untranslated subpages below to make sure we build all levels of the sidenav in localizationed docs sets */}}
Expand All @@ -60,44 +60,26 @@
{{ $withChild := gt (len $pages) 0 -}}
{{ $manualLink := cond (isset $s.Params "manuallink") $s.Params.manualLink ( cond (isset $s.Params "manuallinkrelref") (relref $s $s.Params.manualLinkRelref) $s.RelPermalink) -}}
{{ $manualLinkTitle := cond (isset $s.Params "manuallinktitle") $s.Params.manualLinkTitle $s.Title -}}

{{ $isForeignLanguage := (ne (string $s.Lang) ($.currentLang)) -}}
<li class="td-sidebar-nav__section-title td-sidebar-nav__section{{ if $withChild }} with-child{{ else }} without-child{{ end }}{{ if $activePath }} active-path{{ end }}{{ if (not (or $show $p.Site.Params.ui.sidebar_menu_foldable )) }} collapse{{ end }}" id="{{ $mid }}-li">
{{ if (and $p.Site.Params.ui.sidebar_menu_foldable (ge $ulNr 1)) -}}
<input type="checkbox" id="{{ $mid }}-check"{{ if $activePath}} checked{{ end }}/>
<label for="{{ $mid }}-check"><a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left pl-0 {{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span></a></label>
<input type="checkbox" id="{{ $mid }}-check"{{ if $activePath}} checked{{ end }}/>
<label for="{{ $mid }}-check"><a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left pl-0 {{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span>{{ if $isForeignLanguage }} <small title="{{ T (printf "i18n_language_name_long_%s" $s.Lang ) }}">({{ $s.Lang | upper }})</small>{{ end -}}</a></label>
{{ else -}}
{{ if not $treeRoot }}
<a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left pl-0{{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span></a>
{{ end -}}
{{ end -}}
{{ if $withChild -}}
{{ $ulNr := add $ulNr 1 -}}
<ul class="ul-{{ $ulNr }}{{ if (gt $ulNr 1)}} foldable{{end}}">
{{ $pages := where (union $s.Pages $s.Sections).ByWeight ".Params.toc_hide" "!=" true -}}
{{ with site.Params.language_alternatives -}}
{{ range . }}
{{ with (where $.section.Translations ".Lang" . ) -}}
{{ $p := index . 0 -}}
{{ $pages = where ( $pages | lang.Merge (union $p.Pages $p.Sections)) ".Params.toc_hide" "!=" true -}}
{{ end -}}
{{ end -}}
{{ end -}}
{{ $pages := $pages | first 50 -}}
{{ range $pages -}}
{{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true)) ) -}}
{{ $mid := printf "m-%s" (.RelPermalink | anchorize) -}}
{{ $active := eq . $p -}}
{{ $isForeignLanguage := (ne (string .Lang) (string $.currentLang)) -}}
{{ if (and $isForeignLanguage ($p.IsDescendant $s)) -}}
<a class="td-sidebar-link td-sidebar-link__page {{ if and (not $shouldDelayActive) $active }} active{{ end }}" id="{{ $mid }}" {{ if $isForeignLanguage }}target="_blank"{{ end }} href="{{ .RelPermalink }}">
{{ .LinkTitle }}{{ if $isForeignLanguage }} <small>({{ .Lang | upper }})</small>{{ end -}}
</a>
{{ else -}}
{{ template "section-tree-nav-section" (dict "page" $p "section" . "currentLang" $.currentLang "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow) }}
{{- end }}
{{- end }}
{{- end }}
</ul>
{{ if not $treeRoot }}
<a href="{{ $manualLink }}"{{ if ne $s.LinkTitle $manualLinkTitle }} title="{{ $manualLinkTitle }}"{{ end }}{{ with $s.Params.manualLinkTarget }} target="{{ . }}"{{ if eq . "_blank" }} rel="noopener"{{ end }}{{ end }} class="align-left pl-0{{ if $active}} active{{ end }} td-sidebar-link{{ if $s.IsPage }} td-sidebar-link__page{{ else }} td-sidebar-link__section{{ end }}{{ if $treeRoot }} tree-root{{ end }}" id="{{ $mid }}">{{ with $s.Params.Icon}}<i class="{{ . }}"></i>{{ end }}<span class="{{ if $active }}td-sidebar-nav-active-item{{ end }}">{{ $s.LinkTitle }}</span>{{ if $isForeignLanguage }} <small title="{{ T (printf "i18n_language_name_long_%s" $s.Lang ) }}">({{ $s.Lang | upper }})</small>{{ end -}}</a>
{{- end }}
{{- end }}
{{- if $withChild }}
{{- $ulNr := add $ulNr 1 }}
<ul class="ul-{{ $ulNr }}{{ if (gt $ulNr 1)}} foldable{{end}}">
{{ range $pages -}}
{{ $mid := printf "m-%s" (.RelPermalink | anchorize) -}}
{{ if (not (and (eq $s $p.Site.Home) (eq .Params.toc_root true))) -}}
{{ template "section-tree-nav-section" (dict "page" $p "section" . "shouldDelayActive" $shouldDelayActive "sidebarMenuTruncate" $sidebarMenuTruncate "ulNr" $ulNr "ulShow" $ulShow "currentLang" $currentLang) }}
{{- end }}
{{- end }}
</ul>
{{- end }}
</li>
{{- end }}
{{- end }}
2 changes: 1 addition & 1 deletion themes/docsy
Open in desktop
Submodule docsy updated 90 files
+26 −8 CHANGELOG.md
+60 −0 CONTRIBUTING.md
+9 −0 Dockerfile
+33 −17 assets/scss/_taxonomy.scss
+1 −0 assets/scss/main.scss
+2 −0 assets/scss/shortcodes.scss
+19 −0 assets/scss/shortcodes/cards-pane.scss
+39 −0 assets/scss/shortcodes/tabbed-pane.scss
+14 −0 docker-compose.yaml
+1 −1 go.mod
+1 −1 i18n/ar.toml
+1 −1 i18n/bg.toml
+16 −10 i18n/bn.toml
+1 −3 i18n/de.toml
+1 −1 i18n/en.toml
+2 −2 i18n/es.toml
+1 −1 i18n/et.toml
+1 −1 i18n/fa.toml
+1 −1 i18n/fr.toml
+1 −1 i18n/hu.toml
+1 −1 i18n/it.toml
+1 −1 i18n/ja.toml
+1 −1 i18n/ko.toml
+1 −1 i18n/nl.toml
+1 −1 i18n/no.toml
+1 −1 i18n/pl.toml
+1 −1 i18n/pt-br.toml
+14 −10 i18n/ru.toml
+81 −0 i18n/sv.toml
+1 −1 i18n/tr.toml
+6 −2 i18n/uk.toml
+1 −1 layouts/_default/baseof.html
+5 −2 layouts/_default/taxonomy.html
+1 −1 layouts/blog/baseof.html
+1 −1 layouts/blog/baseof.print.html
+1 −1 layouts/docs/baseof.html
+1 −1 layouts/docs/baseof.print.html
+6 −3 layouts/partials/breadcrumb.html
+1 −1 layouts/partials/community_links.html
+1 −1 layouts/partials/head.html
+1 −1 layouts/partials/page-meta-links.html
+3 −1 layouts/partials/search-input.html
+2 −2 layouts/partials/sidebar-tree.html
+36 −0 layouts/shortcodes/readfile.html
+0 −8 layouts/shortcodes/readfile.md
+22 −11 layouts/shortcodes/tab.html
+95 −18 layouts/shortcodes/tabpane.html
+1 −1 layouts/swagger/baseof.html
+1 −1 netlify.toml
+2 −2 package.json
+0 −2 static/css/shortcodes.css
+0 −21 static/css/shortcodes/cards-pane.css
+0 −18 static/css/shortcodes/tabbed-pane.css
+3 −3 static/js/tabpane-persist.js
+0 −7 userguide/config.toml
+ − userguide/content/en/docs/Adding content/Shortcodes/flags/de.png
+ − userguide/content/en/docs/Adding content/Shortcodes/flags/tz.png
+ − userguide/content/en/docs/Adding content/Shortcodes/flags/uk.png
+11 −0 userguide/content/en/docs/Adding content/Shortcodes/includes/config.yaml
+10 −0 userguide/content/en/docs/Adding content/Shortcodes/includes/installation.md
+215 −50 userguide/content/en/docs/Adding content/Shortcodes/index.md
+459 −55 userguide/content/en/docs/Adding content/content.md
+308 −41 userguide/content/en/docs/Adding content/diagrams-and-formulae/index.md
+140 −17 userguide/content/en/docs/Adding content/feedback.md
+26 −5 userguide/content/en/docs/Adding content/iconsimages.md
+55 −12 userguide/content/en/docs/Adding content/lookandfeel.md
+310 −66 userguide/content/en/docs/Adding content/navigation.md
+66 −7 userguide/content/en/docs/Adding content/print.md
+188 −26 userguide/content/en/docs/Adding content/repository-links.md
+88 −18 userguide/content/en/docs/Adding content/taxonomy.md
+85 −16 userguide/content/en/docs/Adding content/versioning.md
+1 −1 userguide/content/en/docs/Best practices/organizing-content.md
+2 −23 userguide/content/en/docs/Best practices/site-guidance.md
+45 −0 userguide/content/en/docs/Contribution guidelines/_index.md
+47 −23 userguide/content/en/docs/Deployment/_index.md
+4 −3 userguide/content/en/docs/Examples/_index.md
+1 −1 userguide/content/en/docs/Get started/Docsy-As-Module/_index.md
+13 −8 userguide/content/en/docs/Get started/Docsy-As-Module/example-site-as-template.md
+17 −12 userguide/content/en/docs/Get started/Docsy-As-Module/installation-prerequisites.md
+27 −16 userguide/content/en/docs/Get started/Docsy-As-Module/start-from-scratch.md
+2 −2 userguide/content/en/docs/Get started/_index.md
+4 −4 userguide/content/en/docs/Get started/other-options.md
+1 −1 userguide/content/en/docs/Get started/quickstart-docker.md
+48 −5 userguide/content/en/docs/Language/_index.md
+62 −28 userguide/content/en/docs/Updating/Convert-site-to-module.md
+6 −7 userguide/content/en/docs/Updating/Updating-hugo-module.md
+20 −13 userguide/content/en/docs/Updating/Updating-submodules.md
+2 −2 userguide/content/en/docs/Updating/_index.md
+2 −2 userguide/content/en/docs/_index.md
+2 −0 userguide/package.json