Skip to content

Commit 24020b6

Browse files
efiacoraravindtgaCopilot
authored
docs: add versioned docs build with tag-based snapshots (#980)
* docs: versioned docs build with tag-based snapshots - Add versions.json as single source of truth for version entries - Add build-versioned-docs.sh: presentation from main, content from tags - Dynamic tag resolution via tagPattern globs (no manual patch bumps) - Update netlify.toml to use versioned build script - Update config.toml: new baseURL (kpt-porch.netlify.app), sidebar foldable fix, version dropdown generated from versions.json - Align Docsy v0.15.0 and tool versions with kpt site - Drop docsy/dependencies module (bundled in v0.15.0) Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> * Address copilot comments Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> * Address copilot comments Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> * Increase versions font size Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> * Update docs/config.toml Co-authored-by: Aravindhan Ayyanathan <aravindhan.a@est.tech> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> --------- Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech> Co-authored-by: Aravindhan Ayyanathan <aravindhan.a@est.tech> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent aef1a18 commit 24020b6

9 files changed

Lines changed: 329 additions & 18 deletions

File tree

‎docs/assets/scss/_sidebar-left.scss‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,21 @@
33
padding-bottom: 20px;
44
padding-top: 1rem;
55
background-color: $td-sidebar-bg-color;
6+
7+
.td-sidebar-version {
8+
padding-top: 0.5rem;
9+
padding-bottom: 0.5rem;
10+
border-bottom: 1px solid #ddd;
11+
12+
.td-version-menu {
13+
.nav-link {
14+
color: $black;
15+
padding: 0.25rem 0;
16+
font-size: 1rem;
17+
font-weight: 600;
18+
}
19+
}
20+
}
621
.td-sidebar__inner {
722
@media (min-width: 1200px) {
823
top: 4rem;
@@ -52,7 +67,8 @@
5267
&::after {
5368
display: inline-flex;
5469
content: '\f078';
55-
font-family: 'Font Awesome 5 Free';
70+
font-family: 'Font Awesome 6 Free';
71+
font-weight: 900;
5672
}
5773
}
5874
&.active-path {

‎docs/config.toml‎

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
baseURL = 'https://docs.porch.nephio.org/'
1+
baseURL = '/'
22
Locale = 'en-us'
33
title = 'Porch Documentation'
44

@@ -49,6 +49,8 @@ pygmentsStyle = "tango"
4949

5050
copyright = "The kpt Authors"
5151

52+
site_description = "Porch is a Kubernetes-based package management system for KRM configuration packages stored in Git repositories. It consists of an aggregated API server and a set of controllers that handle repository synchronisation, package revision lifecycle, rendering, and automation (PackageVariant/PackageVariantSet). Porch exposes package operations as Kubernetes resources, enabling GitOps workflows with approval gates, automated fan-out, and multi-repository collaboration."
53+
5254
#privacy_policy = ""
5355

5456
code_of_conduct = "https://lfprojects.org/policies/code-of-conduct/"
@@ -84,7 +86,7 @@ version_kpt = "v1.0.0-beta.62.1"
8486
# A link to latest version of the docs. Used in the "version-banner" partial to
8587
# point people to the main doc site.
8688

87-
url_latest_version = "https://docs.porch.nephio.org/docs/"
89+
url_latest_version = "/"
8890

8991
# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
9092

@@ -190,11 +192,8 @@ enable = false
190192
# icon = "fa fa-envelope"
191193
# desc = "Discuss development issues around the project"
192194

193-
# Add your release versions here
194-
195-
[[params.versions]]
196-
version = "latest"
197-
url = "https://docs.porch.nephio.org/docs/"
195+
# Version selector entries are generated from docs/versions.json
196+
# by the build script. Do not add [[params.versions]] here.
198197

199198
[[menu.main]]
200199
name = "Book"

‎docs/content/en/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ toc_hide: true
99
<div class="row mt-5 mb-3">
1010
<div class="col-lg-6">
1111
<div class="lead">
12-
Porch is a Kubernetes extension apiserver that manages the lifecycle of KRM configuration packages in Git repositories. It provides package operations through Kubernetes resources, enabling GitOps workflows with approval gates, automation, and collaboration.
12+
{{< site_description >}}
1313
</div>
1414
</div>
1515
<div class="col-lg-6 text-center td-home-hero-logo">

‎docs/layouts/partials/navbar.html‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,6 @@
1515
<a class="nav-link{{if $active }} active{{end}}" href="{{ with .Page }}{{ .RelPermalink }}{{ else }}{{ .URL | relLangURL }}{{ end }}"><span{{if $active }} class="active"{{end}}>{{ .Name }}</span></a>
1616
</li>
1717
{{ end }}
18-
{{ if .Site.Params.versions }}
19-
<li class="nav-item dropdown me-4 d-none d-lg-block">
20-
{{ partial "navbar-version-selector.html" . }}
21-
</li>
22-
{{ end }}
2318
{{ if (gt (len .Site.Home.Translations) 0) }}
2419
<li class="nav-item dropdown me-4 d-none d-lg-block">
2520
{{ partial "navbar-lang-selector.html" . }}

‎docs/layouts/partials/sidebar.html‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
{{/* Custom sidebar: adds version selector above the navigation tree */}}
2+
3+
{{ $sidebarCacheLimit := .Site.Params.ui.sidebar_cache_limit | default 2000 -}}
4+
{{ $cacheSidebar := ge (len .Site.Pages) $sidebarCacheLimit -}}
5+
{{ $sidebarRoot := or .FirstSection (.Site.GetPage "section" "docs") -}}
6+
{{ $sidebarRootID := "" -}}
7+
{{ with $sidebarRoot -}}
8+
{{ $sidebarRootID = .RelPermalink -}}
9+
{{ end -}}
10+
{{ $args := dict
11+
"context" .
12+
"cacheSidebar" $cacheSidebar
13+
"sidebarRoot" $sidebarRoot
14+
"sidebarRootID" $sidebarRootID
15+
-}}
16+
17+
<div id="td-sidebar-menu" class="td-sidebar__inner">
18+
{{ if .Site.Params.versions }}
19+
<div class="td-sidebar-version mb-3 ps-3 pe-3">
20+
{{ partial "navbar-version-selector.html" . }}
21+
</div>
22+
{{ end }}
23+
{{ if $cacheSidebar -}}
24+
{{ $mid := printf "m-%s" (.RelPermalink | anchorize) }}
25+
<script>
26+
$(function() {
27+
$("#td-section-nav a").removeClass("active");
28+
$("#td-section-nav #{{ $mid }}").addClass("active");
29+
$("#td-section-nav #{{ $mid }}-li span").addClass("td-sidebar-nav-active-item");
30+
$("#td-section-nav #{{ $mid }}").parents("li").addClass("active-path");
31+
$("#td-section-nav li.active-path").addClass("show");
32+
$("#td-section-nav li.active-path").children("input").prop('checked', true);
33+
$("#td-section-nav #{{ $mid }}-li").siblings("li").addClass("show");
34+
$("#td-section-nav #{{ $mid }}-li").children("ul").children("li").addClass("show");
35+
$("#td-sidebar-menu").removeClass("d-none");
36+
});
37+
</script>
38+
{{ partialCached "sidebar-tree.html" $args $sidebarRootID }}
39+
{{ else -}}
40+
{{ partial "sidebar-tree.html" $args }}
41+
{{ end }}
42+
</div>

‎docs/layouts/shortcodes/site_description.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ .Site.Params.site_description | markdownify }}

‎docs/netlify.toml‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,8 @@
11
# Hugo build configuration for Netlify
2-
# (https://gohugo.io/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify)
32

43
[build]
54
base = "docs"
6-
command = "hugo --environment $HUGO_ENV"
5+
command = "../scripts/build-versioned-docs.sh"
76
publish = "public"
87
ignore = "false" # Always build
98

@@ -16,10 +15,8 @@
1615
[context.production.environment]
1716
HUGO_ENV = "production"
1817

19-
# Deploy previews (pull requests) context
2018
[context.deploy-preview.environment]
2119
HUGO_ENV = "development"
2220

23-
# Branch deploys context
2421
[context.branch-deploy.environment]
2522
HUGO_ENV = "development"

‎docs/versions.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[
2+
{
3+
"version": "latest",
4+
"tagPattern": null,
5+
"path": "/"
6+
},
7+
{
8+
"version": "v1.5",
9+
"tagPattern": "v1.5.*",
10+
"path": "/v1.5/"
11+
}
12+
]

0 commit comments

Comments
 (0)