aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--.builds/docs.yml10
-rw-r--r--docs/js/version-selector.js39
-rw-r--r--mkdocs.yml3
-rwxr-xr-xscripts/deploy-docs.sh90
4 files changed, 133 insertions, 9 deletions
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 "$@"