Skip to content

Commit 62d4aac

Browse files
chalinchalin
committed
Add site build info and build documentation
- Adds a new shortcode to display Netlify build info - Updates the main site documentation to include this info - Adds a new 'build' section with details on the repository structure and branch model.
1 parent 1465641 commit 62d4aac

File tree

10 files changed

+219
-5
lines changed

10 files changed

+219
-5
lines changed

‎.markdownlint-cli2.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
# cSpell:ignore docsy github lookandfeel iconsimages
22

33
globs:
4+
- '!docsy.dev/**'
5+
- '!layouts/**'
46
- '!node_modules/**'
57
- '!public/**'
68
- '!tmp/**'
7-
- '!docsy.dev/**'
89
- docsy.dev/content/en/docs/content/iconsimages.md
910
- docsy.dev/content/en/docs/content/language.md
1011
- docsy.dev/content/en/docs/content/lookandfeel.md

‎.vscode/cspell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
"Docsy",
99
"errorf",
1010
"Gantt",
11+
"getenv",
1112
"GLFM",
1213
"htmltest",
1314
"hugo",

‎docsy.dev/content/en/site/_index.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: About this website
3-
linkTitle: Website docs
4-
description: How this site is built, maintained, and deployed.
2+
title: Project and website documentation
3+
linkTitle: Project docs
4+
description: How Docsy theme and website are built, maintained, and deployed.
55
aliases: [project]
66
cascade:
77
outputs: [HTML]
@@ -10,6 +10,7 @@ cascade:
1010
hide_feedback: true
1111
params:
1212
FA: <i class="fa-solid fa-{1} text-{2}"></i>
13+
cSpell:ignore: docsydocs
1314
---
1415

1516
Planned content organization (tentative)
@@ -29,3 +30,7 @@ Planned content organization (tentative)
2930

3031
{{% _param FA person-digging " pe-2" %}} This section is under development. {{%
3132
_param FA person-digging " ps-2" %}}
33+
34+
## Site build information
35+
36+
{{% td/site-build-info/netlify team="docsydocs" %}}

‎docsy.dev/content/en/site/build/_index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Build
3+
description: >
4+
Tooling, local development setup, CI/CD workflows, deployment environments,
5+
and automation details.
6+
weight: 100
7+
---

‎docsy.dev/content/en/site/build/git-repo.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Git repository information
3+
linkTitle: Git repo
4+
cSpell:ignore: docsy hotfixes
5+
---
6+
7+
## Monorepo
8+
9+
The Docsy repository is effectively a **monorepo** containing the Docsy:
10+
11+
- **Theme** at the repo root
12+
- **Website** in the `docsy.dev` directory
13+
14+
## Branch model
15+
16+
The repo has two main branches:
17+
18+
- `main`: development branch
19+
- All feature work and doc updates land here first.
20+
- Source of leading-edge theme version for downstream sites.
21+
22+
- `release` branch
23+
- Published & supported line of the theme and website.
24+
- Website production builds are deployed from this branch via Netlify.
25+
- An ancestor of `main` most of the time, diverged due to hotfixes on
26+
occasion.
27+
28+
No rebases and no history rewriting for either branch.
29+
30+
### Tags
31+
32+
- Tags are used for **official theme releases**
33+
- Tags are attached to `main` commits, which are shared by `release` since the
34+
two branches sync on releases.
35+
36+
### Release flow
37+
38+
1. Work merges into `main`.
39+
2. At release:
40+
- Tag the release commit on `main`.
41+
- Fast-forward `release` to that same commit.
42+
3. Netlify deploys from `release`.
43+
44+
This keeps history mostly linear.
45+
46+
### Hotfixes (rare)
47+
48+
- If a fix lands on `release`, it must be forward-merged or cherry-picked to
49+
`main`.
50+
- Next promotion fast-forwards `release` to `main` again.
51+
52+
Invariant: `release` should converge back to `main` ASAP.
53+
54+
## Why this model?
55+
56+
- Preserves a clean, mostly linear history.
57+
- Allows website production deploys on release commits (and a rare hotfix).
58+
- Keeps `main` free for ongoing theme + site development.
59+
- Maintains clear, immutable release points for theme consumers via tags.

‎docsy.dev/content/en/site/implementation/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ linkTitle: Implementation
44
description:
55
Code-level structure and conventions, Hugo/Docsy templates, SCSS/JS
66
customizations, patches, and internal shims.
7+
weight: 100
78
no_list: true
89
---
910

‎docsy.dev/hugo.yaml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,16 @@ taxonomies:
149149
tag: tags
150150
category: categories
151151

152+
# Allow Netlify build environment variables to be accessed in templates.
153+
#
154+
# TODO: consider instead using a CI script to write the build information to a
155+
# data file that Hugo could read.
156+
security:
157+
funcs: # cspell:disable-line
158+
getenv: # cspell:disable-line
159+
# Netlify build env var
160+
- ^(BRANCH|BUILD_ID|COMMIT_REF|CONTEXT|DEPLOY_ID|NETLIFY|PULL_REQUEST|REVIEW_ID)$
161+
152162
module:
153163
mounts:
154164
- source: content/en

‎docsy.dev/scripts/test-netlify-env.sh‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
#!/bin/bash
2+
3+
# Test environment variables for Netlify build info shortcode
4+
# Usage: (source scripts/test-netlify-env.sh && npm run serve)
5+
6+
export BRANCH="main"
7+
export BUILD_ID="6969a939575aaf0008ac7a48"
8+
export COMMIT_REF="884d714b43e317c83fb9df0a0a25346f1bea4974"
9+
export DEPLOY_ID="6969a939575aaf0008ac7a48"
10+
export NETLIFY="true"
11+
export PULL_REQUEST="false"
12+
export REVIEW_ID=""
13+
export CONTEXT="deploy-preview"
14+
15+
# Uncomment to test PR build scenario:
16+
# export PULL_REQUEST="true"
17+
# export REVIEW_ID="1234"
18+
# export CONTEXT="deploy-preview"
19+
20+
# Uncomment to test production build:
21+
# export CONTEXT="production"
22+
23+
# Uncomment to test local build (no Netlify):
24+
# unset NETLIFY
25+
# export CONTEXT="local"
26+
27+
echo "Netlify test environment variables set:"
28+
echo " BRANCH=$BRANCH"
29+
echo " BUILD_ID=$BUILD_ID"
30+
echo " COMMIT_REF=$COMMIT_REF"
31+
echo " DEPLOY_ID=$DEPLOY_ID"
32+
echo " NETLIFY=$NETLIFY"
33+
echo " PULL_REQUEST=$PULL_REQUEST"
34+
echo " REVIEW_ID=$REVIEW_ID"
35+
echo " CONTEXT=$CONTEXT"
36+
echo ""
37+
echo "To use: source scripts/test-netlify-env.sh"
38+
echo "Then run: npm run serve (or your build command)"

‎layouts/_shortcodes/td/site-build-info/netlify.md‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
{{/*
2+
3+
@param {string} [0/team] Netlify App team name.
4+
@param {string} [1/repoURL] The repository URL, optional. Defaults to site param `github_repo`.
5+
6+
*/ -}}
7+
8+
{{ $scName := "site-build-info/netlify" -}}
9+
10+
{{ $team := .Get 0 | default (.Get "team") -}}
11+
12+
{{ if not $team -}}
13+
{{ warnf "%s: shortcode %q: parameter 0 ('team') is missing" .Position $scName -}}
14+
{{ end -}}
15+
16+
{{ $repoURL := .Get 1 | default (.Get "repoURL") | default (.Page.Param "github_repo") -}}
17+
18+
{{ if not $repoURL -}}
19+
{{ $msg := add
20+
"parameter 1 ('repoURL') is missing and "
21+
"site param 'github_repo' is not defined."
22+
-}}
23+
{{ warnf "%s: shortcode %q: %s" .Position $scName $msg -}}
24+
{{ else if hasSuffix $repoURL "/" -}}
25+
{{ $repoURL = strings.TrimSuffix $repoURL "/" -}}
26+
{{ end -}}
27+
28+
{{ $branch := os.Getenv "BRANCH" -}}
29+
{{ $buildID := os.Getenv "BUILD_ID" -}}
30+
{{ $commitRef := os.Getenv "COMMIT_REF" -}}
31+
{{ $deployID := os.Getenv "DEPLOY_ID" -}}
32+
{{ $isNetlifyBuilt := os.Getenv "NETLIFY" | default false -}}
33+
{{ $isPR := os.Getenv "PULL_REQUEST" -}}
34+
{{ $reviewID := os.Getenv "REVIEW_ID" -}}
35+
{{ $now := now -}}
36+
37+
Netlify build information:
38+
39+
| Attribute | Value |
40+
|---|---|
41+
Netlify built | `{{ $isNetlifyBuilt }}`
42+
{{/**/ -}}
43+
44+
{{/*Don't show timestamp for local builds to avoid affecting site diffs. */ -}}
45+
{{ with $isNetlifyBuilt -}}
46+
Date/time[^date] | {{ $now.Format "2006-01-02 15:04 MST" }}[^local-time]
47+
{{ end -}}
48+
{{/**/ -}}
49+
50+
{{ with $buildID -}}
51+
ID | `{{.}}`
52+
{{ end -}}
53+
{{/**/ -}}
54+
55+
{{ with $deployID -}}
56+
Deploy log | [{{ . }}](https://app.netlify.com/teams/{{ $team }}/builds/{{ . }})
57+
{{ end -}}
58+
{{/**/ -}}
59+
60+
{{ with $reviewID -}}
61+
Build context |
62+
{{- if $isPR -}}
63+
[PR #{{ . }}]({{ $repoURL }}/pull/{{ . }})
64+
{{ else -}}
65+
merge `{{ . }}`
66+
{{ end -}}
67+
{{ end -}}
68+
{{/**/ -}}
69+
70+
Deploy context | {{ os.Getenv "CONTEXT" | default "local" }}
71+
{{/**/ -}}
72+
73+
{{ with $commitRef -}}
74+
Commit | [@{{substr . 0 7 }}]({{ $repoURL }}/commit/{{ . }})
75+
{{ end -}}
76+
{{/**/ -}}
77+
78+
{{ with $branch -}}
79+
Branch | `{{ . }}`
80+
{{ end -}}
81+
{{/*End of table*/}}
82+
83+
[^date]: Approximate build timestamp.
84+
[^local-time]: In your timezone: <span id="local-time">unknown</span>.
85+
86+
<script>
87+
document.addEventListener("DOMContentLoaded", function() {
88+
var options = { hour: '2-digit', hour12: false, minute: '2-digit', timeZoneName: 'short' };
89+
var buildDate = new Date("{{ $now.Format "2006-01-02T15:04:05Z07:00" }}");
90+
document.getElementById("local-time").innerText = buildDate.toLocaleString(undefined, options);
91+
});
92+
</script>

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "docsy",
3-
"version": "0.14.0-dev+16-g68cb0e7",
3+
"version": "0.14.0-dev+20-g1465641",
44
"repository": "github:google/docsy",
55
"homepage": "https://www.docsy.dev",
66
"license": "Apache-2.0",

0 commit comments

Comments
 (0)