Conversation
Reported bug: when viewing a numbered section that lives in a single file (Sections 0, 1, 2, 5, 6, 7), the sidebar didn't show which sub-section the user was reading. Clicking "5.1 Software Development & CI/CD" in the sidebar scrolled to that section but the sidebar still highlighted "Section 5 (overview)" — there was no visual cue that "5.1" was the active sub-item. Root cause: Starlight's left sidebar matches active state by URL pathname only, ignoring the URL hash. Sidebar items written as anchors within a single page (the 5.1, 5.2, etc. items in sections 0/1/2/5/6/7) never get an active indicator out of the box. Fix: 1. New script public/scripts/sidebar-scrollspy.js (~110 lines, vanilla JS, no deps). On page load and on hashchange, marks the sidebar item whose link matches the current URL hash. On scroll (rAF- throttled), tracks which H2/H3 is closest to the top of the viewport and marks the corresponding sidebar anchor as active. When a sub-anchor is active, dims the "Section X (overview)" pathname-matched item so there's only one "you are here" indicator. 2. Wired in via astro.config.mjs head <script defer> reference. 3. CSS in custom.css adds a visible active state for sidebar anchor sub-items: accent-coloured background, accent text, bold weight, plus a 3px accent stripe down the left edge — matches Starlight's visual language for the standard active item. The script is a no-op on pages whose sidebar entries don't include any anchor sub-items (Sections 3, 4, About ADS, Resources, etc.) — it only attaches scroll/hashchange listeners when the current page actually has anchor links to track. Build verified: 154 pages, no errors. Script reference present in built HTML; no console errors expected.
When the NHS-removal substitution replaced 'HSCN' with 'national
healthcare secure network', it inadvertently turned a single-word
Mermaid node ID into a multi-word string. Mermaid 11 (and earlier)
require node IDs to be single tokens — spaces in IDs are a syntax
error.
The 3.3.1 deployment diagram on the Medwick example page was
rendering as a "Syntax error in text" bomb because of this.
Fix: use 'SecNet' as the single-word node ID, with the original
'National Healthcare Secure Network' as the displayed label:
Before:
AppSvc -. TLS-MA over national healthcare secure network .-> national healthcare secure network[National Healthcare Secure Network]
national healthcare secure network --> Spine[MediCore Spine]
After:
AppSvc -. TLS-MA via secure network .-> SecNet[National Healthcare Secure Network]
SecNet --> Spine[MediCore Spine]
Verified: no other Mermaid blocks across the corpus had the same
problem (the earlier-line 467-468 uses of 'national healthcare secure
network' are inside edge labels — spaces in edge labels are
permitted by Mermaid).
Build clean.
…h corrected acronyms, en-GB language
Three connected issues all visible in public/templates/sad-template.docx:
1. Wide multi-column tables looked horrible in A4 portrait Word.
Schema arrays with 11+ properties (e.g. dataStores) became
illegible: column widths squashed to 1-2 chars wide, content
wrapping inside cells in unhelpful ways.
Fix in scripts/generate-templates.cjs: when an array's items
have more than 5 properties, render as a vertical Field/Value
form per item (with a "Repeat the table below for each X" hint)
instead of one wide horizontal row. Threshold = 5 columns.
Result: 12 wide tables in the SAD template now use the
vertical layout — readable in any output format.
2. The Word doc still had pre-acronym-fix labels ("Api Service",
"Saml", "Mqtt", "Oidc", "Smtp", "Jdbc", "Iam Role"). The .md
was regenerated when I fixed the acronym dictionary in commit
1130086, but the .docx wasn't — it was a separate manual
pandoc step that hadn't been re-run.
Fix in scripts/generate-templates.cjs: integrated docx
generation into the npm run generate:templates pipeline so
future schema regens automatically refresh the docx too.
Best-effort (skips silently if Pandoc isn't installed).
Verified: 0 bad acronyms, all correct (API, SAML, MQTT, OIDC,
SMTP, JDBC, IAM) in the regenerated docx.
3. Word doc didn't have an explicit en-GB language tag. Word's
spell-checker would default to the OS language, marking UK
spellings as errors for some users.
Fix: --metadata=lang:en-GB passed to Pandoc, which writes
dc:language=en-GB into docProps/core.xml. Verified.
Also updated scripts/generate-pdf.cjs (the full-standard doc
generator) to set en-GB on its DOCX and PDF outputs too.
Build verified: 154 pages, no errors. SAD template docx
regenerated and shows acronyms correct, vertical layout for
wide arrays, dc:language=en-GB.
Two related issues, both flagged by Gemini reviewing the validation
code samples:
1. The validation examples used 'npx ajv -s <URL>' which doesn't work
— ajv-cli's -s flag expects a local file path, not a URL. Same for
Python's jsonschema CLI.
Fix: every example now downloads the schema first with curl, then
validates locally:
curl -O https://archstandard.org/schema/v1.0.0/ads.schema.json
npx -p ajv-cli ajv validate -s ads.schema.json -d my-sad.json
Also corrected the npx invocation: 'npx -p ajv-cli ajv ...' is the
correct form (the binary is 'ajv', from package 'ajv-cli'), not
'npx ajv-cli'.
Updated in three places:
- src/content/docs/examples/index.mdx
- src/content/docs/standard/faq.mdx
- src/content/docs/standard/schema.mdx
2. The schema's own $id is "https://archstandard.org/schema/v1.0.0/
ads.schema.json" (no /v1/) but the file was being served at
"/v1/schema/v1.0.0/..." after the post-build script moved
everything into /v1/. Tooling resolving the canonical $id URL
would 404.
Fix: scripts/post-build.cjs now keeps 'schema/' at the dist root,
matching the schema's $id. Schemas are versioned independently of
the website (the schema URL has its own /v1.0.0/ segment), so
keeping them at root is the right architectural choice.
Also normalised remaining /v1/schema/v1.0.0/... links across the
site (downloads.mdx, prompts.mdx, version-history.mdx, examples/
index.mdx, schema.mdx) to use the canonical /schema/v1.0.0/...
URL.
Build verified: 154 pages, dist/schema/v1.0.0/ads.schema.json now
exists at the canonical path; no /v1/schema/ references in the built
HTML.
The SAD template (public/templates/sad-template.{md,yaml,docx}) is
the form a user fills in to create their *own* Solution Architecture
Document. Having "Author: Andi Chandler" in the template header was
misleading — when a user opens the template, the author is them, not
the standard's author.
Removed the Author line from the auto-generated headers in:
- The Markdown template
- The YAML template
- The DOCX template (regenerated from the MD)
Kept the standard-level attribution that genuinely belongs there:
- "Standard: ADS v1.3.0"
- "Standard published by: ArchStandard"
- "Standard licence: CC BY 4.0"
- "Generated from: schema/ads.schema.json"
Added a clarifying line: "Document author and owner: complete in
Section 0 (Document Control) below" — so users know exactly where
to put their own attribution.
Note: scripts/generate-pdf.cjs (which produces the full *standard*
PDF and DOCX, ads-standard-v1.{pdf,docx}) still has "Author: Andi
Chandler" — that's correct, the standard itself is genuinely
authored by Andi. Only the user-facing SAD template was the issue.
Verified: 0 occurrences of "Andi Chandler" in the regenerated
sad-template.docx; ArchStandard and CC BY 4.0 metadata retained.
Two improvements to the user-fillable SAD template Word output: 1. Margins reduced to 15mm (from Pandoc's default ~25mm). With the already-fixed wide-table issue + narrower margins, multi-column tables now have substantially more horizontal room — content reads cleanly instead of squashing into 1-2 character columns. Mechanism: a Pandoc reference docx (scripts/sad-template-reference.docx) with explicit pgMar and A4 pgSz injected. The generate-templates script now passes --reference-doc when this file exists. 2. More acronym fixes: Sre→SRE (the obvious one), plus DevOps, SecOps, MLOps, DataOps, AIOps, DBA — all the operational-role labels that were getting naive title-cased to "Sre", "Devops" etc. Verified: 0 occurrences of "Sre" in the regenerated docx; "SRE" correctly shows in the stakeholder roles checklist. pgMar = 851 twips on all four sides (≈15mm). The reference docx is checked in alongside the script — Pandoc needs the actual docx file at runtime, not a regeneration step.
…oll-spy blue
Three small follow-ups to the SAD template + sidebar polish:
1. Acronym dictionary additions (regenerated docx affected):
- Cpu/Cpus -> CPU/CPUs, Gpu/Gpus -> GPU/GPUs, Ram -> RAM
- Rhel -> RHEL, Suse -> SUSE, Centos -> CentOS
- Qa -> QA
- Cyberark -> CyberArk
- Cicd -> CI/CD (with the slash, not naive titlecase)
- Tradeoff/Tradeoffs -> Trade-off/Trade-offs (hyphenated)
- Plus DBA/DBAs from earlier
2. "Quality Attribute Refs" -> "Quality Attribute References"
The schema field is qualityAttributeRefs and the auto-generated
label was "Quality Attribute Refs" — abbreviating "References" to
"Refs" is informal. Now consistently rendered as the full word
across all 5 occurrences in the template.
3. Sidebar scroll-spy active state was using the wrong CSS variable
pair (--sl-color-text-accent + --sl-color-accent-low), which
produced a darker-navy background than Starlight's standard active
highlight. Now uses --sl-color-text-invert + --sl-color-text-accent
to match Starlight's [aria-current=page] styling exactly — anchor
sub-items now have the same blue highlight as slug-matched current
pages.
4. Bonus fix: the "Repeat the table below for each X" hint had a
typo ("for each dependencie") because of naive trailing-s
singularisation. Now uses an "ies -> y" rule plus a small explicit
map for compound plurals like "APIs & Interfaces" -> "API or
interface". All 12 array hints now read cleanly.
No build, content, or schema changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
v1.3.1 — Bug fixes and SAD template polish
Patch release on top of v1.3.0. No content additions, no breaking changes, no schema bump — purely fixes and polish from initial-review feedback.
Bug fixes
HSCN) into a multi-word string, breaking Mermaid syntax. Replaced withSecNetas the node ID.$idishttps://archstandard.org/schema/v1.0.0/...but the post-build script was moving the file into/v1/schema/..., so the URL referenced inside the schema 404'd. Fixed by keepingschema/at the dist root.npx ajv -s <URL>doesn't work — ajv-cli's-sflag expects a local file. Examples inexamples/index.mdx,faq.mdx, andschema.mdxnow show the correctcurl -O … && npx -p ajv-cli ajv validate -s ads.schema.json …pattern.public/scripts/sidebar-scrollspy.js) that updates active state based on URL hash and viewport scroll position. Active styling matches Starlight's[aria-current=page]exactly.SAD template improvements
dataStoreswith 11 properties) were illegible in A4 portrait Word — column widths squashed to 1-2 chars wide. Threshold-driven layout fix in the generator: 12 wide tables in the SAD template now use the vertical form layout with a "Repeat the table below for each X" hint.scripts/sad-template-reference.docx) checked in alongside the generator.lang: en-GBset on the Word doc — Word now uses UK English by default for spell-check, no more red-underlined "organisation" / "optimisation".Cicd)dependencie→dependency) — naive trailing-s singularisation now uses anies → yrule plus a small explicit map for compounds like "APIs & Interfaces" → "API or interface".Tooling
npm run generate:templatesnow also producessad-template.docxvia Pandoc (en-GB) — keeps the four template formats (.json/.yaml/.md/.docx) in sync automatically.scripts/generate-pdf.cjs(full-standard PDF/DOCX generator) updated to uselang: en-GBand--metadata=lang:en-GB.Compatibility
/v1/...URLs remain. Only addition is/schema/v1.0.0/ads.schema.jsonat the canonical (unversioned-by-site) path matching the schema's$id.Files
7 commits, ~13 files changed.
Test plan
public/templates/sad-template.docx— wide tables now vertical, narrow margins, no "Andi Chandler", correct acronyms/v1/standard/5-lifecycle/) — sidebar sub-anchor active state highlights correctly as you scroll