Show the app version, last update and commit in the docs site footer, with the copyright line #200

Merged
ethan-hann merged 3 commits from issue-194-docs-footer into main 2026-10-26 23:27:29 -05:00
Owner

Closes #194.

The documentation site gave no way to tell which version of SavePoint its pages describe or when they were built. Every page now ends in a three-column footer: "Written for SavePoint " (linked to that release) above "Updated <commit time, UTC> from " (linked to the commit); "Copyright (c) Ethan Hann"; and the GPL line.

build/docs-footer.sh builds the footer HTML from Directory.Build.props and the commit (version, UTC time, year, links from GITHUB_SERVER_URL and GITHUB_REPOSITORY, everything HTML-escaped), and docs.yml passes it to docfx as --metadata _appFooter. A local build keeps a fallback in docfx.json ("Built locally", the copyright without a year, the license). The theme fixed the footer at 60px, which cut off the stacked column, so main.css lets the footer fit its content; the columns stack below 768px and the links are underlined like the rest of the site. Directory.Build.props joins the docs workflow's path filters, so a version bump republishes the site with the new version.

Tests: DocsFooterScriptTests (10, run the script against a temp repo with a commit dated across a year boundary in another time zone; they skip on Windows like the other bash-script tests) and DocsWorkflowTests (5, the workflow passes the script's output, the checkout and path filters, the fallback). The local Windows gate passed on this branch, and the layout was checked in a browser at desktop and narrow widths.

Closes #194. The documentation site gave no way to tell which version of SavePoint its pages describe or when they were built. Every page now ends in a three-column footer: "Written for SavePoint <version>" (linked to that release) above "Updated <commit time, UTC> from <short hash>" (linked to the commit); "Copyright (c) <year> Ethan Hann"; and the GPL line. build/docs-footer.sh builds the footer HTML from Directory.Build.props and the commit (version, UTC time, year, links from GITHUB_SERVER_URL and GITHUB_REPOSITORY, everything HTML-escaped), and docs.yml passes it to docfx as --metadata _appFooter. A local build keeps a fallback in docfx.json ("Built locally", the copyright without a year, the license). The theme fixed the footer at 60px, which cut off the stacked column, so main.css lets the footer fit its content; the columns stack below 768px and the links are underlined like the rest of the site. Directory.Build.props joins the docs workflow's path filters, so a version bump republishes the site with the new version. Tests: DocsFooterScriptTests (10, run the script against a temp repo with a commit dated across a year boundary in another time zone; they skip on Windows like the other bash-script tests) and DocsWorkflowTests (5, the workflow passes the script's output, the checkout and path filters, the fallback). The local Windows gate passed on this branch, and the layout was checked in a browser at desktop and narrow widths.
build/docs-footer.sh prints the footer of the documentation site as one line of HTML: 'Written for SavePoint <version>' linking to the release tag, 'Updated <UTC time> from <short hash>' linking to the commit, the copyright with the commit's UTC year, and the license line. The version is read from Directory.Build.props as text, the time from git log -1 of the given commit, and everything that enters the HTML is escaped. It prints nothing and fails when the version or the commit is missing.

docs.yml builds the footer from GITHUB_SHA, GITHUB_SERVER_URL and GITHUB_REPOSITORY and passes it to docfx as one quoted --metadata _appFooter argument, so the server is named nowhere else. The checkout says fetch-depth: 1 (the commit's own date is all the footer needs). A change to Directory.Build.props or the script now builds the site, and a push of the props file publishes it. docfx.json keeps the static footer as the local-build fallback, with 'Copyright &copy; Ethan Hann' and no year. main.css styles the footer small and muted, with theme-colored links that underline on hover and focus.

Observed reds (before build/docs-footer.sh or the workflow change existed):

DocsWorkflowTests, 5 of 5 failed on assertions: 'The build step never runs build/docs-footer.sh.'; the GITHUB_SHA pattern was not found in the build step; no 'fetch-depth: 1' in the checkout step; 'Directory.Build.props' not found in the push paths; 'Copyright &copy; Ethan Hann' not found in the docfx.json footer.

DocsFooterScriptTests, 10 of 10 failed against a stub that printed nothing and exited 0: 8 with 'Assert.Contains() Failure: Sub-string not found' on an empty string (version link, UTC time, commit link, year, license, escaping, trailing slash, given commit), 2 with 'Expected: Not 0, Actual: 0' (missing version, unknown commit). These tests skip on Windows like the other bash-script tests, so the red and green runs were made with the skip lifted and the bash of Git for Windows; they pass 10 of 10 there and on bash 5.1 in WSL. Their names are in build/expected-skips/windows.txt.
The footer showed as one bunched, left-aligned row, and the theme's fixed 60px footer cut off the stacked first column and gave
short pages a scroll bar. The build column (version above the update), the copyright and the license now sit in three centered
columns that stack on a narrow screen, the footer takes the height its content needs with less padding, and its links are
underlined like every other link on the site. The local-build fallback uses the same columns.
Merge remote-tracking branch 'origin/main' into issue-194-docs-footer
All checks were successful
Docs / site (pull_request) Successful in 1m17s
Gate / linux (pull_request) Successful in 17m0s
Gate / windows (pull_request) Successful in 38m18s
Docs / site (push) Successful in 1m17s
0d18da103c
Sign in to join this conversation.
No reviewers
No milestone
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ethan-hann/SavePoint!200
No description provided.