From 3cd15cb2e3aecc4c2e1e553d9ac7e4a7a67c46b1 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 11 Oct 2025 11:08:32 -0400 Subject: Add support for versioned docs --- .builds/docs.yml | 10 +++++ docs/js/version-selector.js | 39 ++++++++++++++++++++ mkdocs.yml | 3 ++ scripts/deploy-docs.sh | 90 ++++++++++++++++++++++++++++++++++++++++----- 4 files changed, 133 insertions(+), 9 deletions(-) create mode 100644 docs/js/version-selector.js diff --git a/.builds/docs.yml b/.builds/docs.yml index dfa8ac9..4316feb 100644 --- a/.builds/docs.yml +++ b/.builds/docs.yml @@ -6,6 +6,9 @@ packages: - mkdocs-material - py3-regex - hut + - jq + - rsync + - git secrets: - ac3eecc9-8fb0-4ed4-ae53-0472c093a1f1 sources: @@ -13,4 +16,11 @@ sources: tasks: - deploy: | cd bolt + + if git describe --exact-match --tags HEAD 2>/dev/null; then + export VERSION=$(git describe --exact-match --tags HEAD) + else + export VERSION=latest + fi + ./scripts/deploy-docs.sh diff --git a/docs/js/version-selector.js b/docs/js/version-selector.js new file mode 100644 index 0000000..fb0a187 --- /dev/null +++ b/docs/js/version-selector.js @@ -0,0 +1,39 @@ +(function () { + fetch("/versions.json") + .then((r) => r.json()) + .then((data) => { + const currentPath = window.location.pathname; + const pathParts = currentPath.split("/").filter((p) => p); + const currentVersion = pathParts[0] || "latest"; + + const header = document.querySelector(".md-header__inner"); + if (!header) return; + + const select = document.createElement("select"); + select.className = "md-version-select"; + select.style.cssText = + "margin-left: 1rem; padding: 0.25rem 0.5rem; border-radius: 0.25rem; background: var(--md-default-bg-color); border: 1px solid var(--md-default-fg-color--lighter);"; + + data.versions.forEach((v) => { + const option = document.createElement("option"); + option.value = v.version; + option.textContent = v.title; + if (v.version === currentVersion) { + option.selected = true; + } + select.appendChild(option); + }); + + select.addEventListener("change", (e) => { + const newVersion = e.target.value; + const remainingPath = pathParts.slice(1).join("/"); + window.location.href = + "/" + newVersion + (remainingPath ? "/" + remainingPath : "/"); + }); + + header.appendChild(select); + }) + .catch((err) => { + console.error("Failed to load version selector:", err); + }); +})(); diff --git a/mkdocs.yml b/mkdocs.yml index 79e161a..e060055 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,9 @@ markdown_extensions: - toc: permalink: true +extra_javascript: + - js/version-selector.js + nav: - Home: index.md - Installation: installation.md diff --git a/scripts/deploy-docs.sh b/scripts/deploy-docs.sh index 7bdae3a..008d571 100755 --- a/scripts/deploy-docs.sh +++ b/scripts/deploy-docs.sh @@ -4,14 +4,19 @@ set -eou pipefail source "$(dirname "${BASH_SOURCE[0]}")/lib/log.sh" readonly SITE="bolt.eugenetriguba.com" +readonly BUILD_DIR="site" usage() { echo "Usage: $0" echo "" - echo "Build and deploy documentation to SourceHut Pages" + echo "Build and deploy versioned documentation to SourceHut Pages" + echo "" + echo "Environment variables:" + echo " VERSION - The version to deploy (default: 'latest' for main branch)" echo "" echo "Examples:" - echo " $0 # Build and deploy docs to $SITE" + echo " $0 # Deploy as 'latest'" + echo " VERSION=v1.0.0 $0 # Deploy as 'v1.0.0'" } main() { @@ -21,27 +26,94 @@ main() { fi log_header "Deploying Documentation" - build_docs + + local version="${VERSION:-latest}" + log_info "Deploying version: $version" + + fetch_existing_site + build_version "$version" + update_versions_manifest + copy_version_assets package_site - deploy_to_pages + deploy_to_pages "$version" +} + +fetch_existing_site() { + log_step "Fetching existing site" + mkdir -p "$BUILD_DIR" + + if hut pages download "$SITE" 2>/dev/null | tar -xzf - -C "$BUILD_DIR" 2>/dev/null; then + log_success "Existing site fetched" + else + log_info "No existing site found, starting fresh" + fi } -build_docs() { - log_step "Building documentation with MkDocs" - mkdocs build - log_success "Documentation built successfully" +build_version() { + local version="$1" + log_step "Building documentation for version: $version" + + mkdocs build -d "$BUILD_DIR/$version" + + # If latest, also copy to root for default view + if [[ "$version" == "latest" ]]; then + log_step "Copying latest to root" + rsync -a --delete "$BUILD_DIR/latest/" "$BUILD_DIR/" \ + --exclude="versions.json" \ + --exclude="v*" \ + --exclude="latest" + fi + + log_success "Documentation built for $version" +} + +update_versions_manifest() { + log_step "Updating versions manifest" + + # Build array of versions using jq + local versions_json="[]" + + # Add 'latest' if it exists + if [[ -d "$BUILD_DIR/latest" ]]; then + versions_json=$(echo "$versions_json" | jq '. += [{"version": "latest", "title": "Latest (Development)"}]') + fi + + # Add all tagged versions (sorted in reverse) + if compgen -G "$BUILD_DIR/v*" > /dev/null; then + for dir in $(find "$BUILD_DIR" -maxdepth 1 -type d -name "v*" | sort -Vr); do + local ver=$(basename "$dir") + versions_json=$(echo "$versions_json" | jq --arg v "$ver" '. += [{"version": $v, "title": $v}]') + done + fi + + # Create final JSON structure + jq -n --argjson versions "$versions_json" '{"versions": $versions}' > "$BUILD_DIR/versions.json" + + local version_count=$(echo "$versions_json" | jq 'length') + log_success "Versions manifest updated with $version_count version(s)" +} + +copy_version_assets() { + log_step "Copying version selector assets" + # Copy the JS file that was built into each version to the root + if [[ -f "$BUILD_DIR/latest/js/version-selector.js" ]]; then + cp "$BUILD_DIR/latest/js/version-selector.js" "$BUILD_DIR/version-selector.js" + log_success "Version selector copied to root" + fi } package_site() { log_step "Creating tarball" - tar -C site -czf site.tar.gz . + tar -C "$BUILD_DIR" -czf site.tar.gz . log_success "Site packaged as site.tar.gz" } deploy_to_pages() { + local version="$1" log_step "Deploying to SourceHut Pages: $SITE" hut pages publish -d "$SITE" site.tar.gz log_success "Documentation deployed to https://$SITE" + log_info "Version URL: https://$SITE/$version/" } main "$@" -- cgit v1.2.3