Skip to content

Commit 6d6528d

Browse files
CataldirCataldir
authored
Merge branch 'main' into feature/1022-pagefind-app-search
2 parents 73ecf6a + ba85eab commit 6d6528d

14 files changed

Lines changed: 688 additions & 8 deletions

‎.github/workflows/deploy-ui-swa.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,38 @@ jobs:
8989
with:
9090
node-version: '20'
9191

92+
- name: Setup Python (mkdocs build)
93+
uses: actions/setup-python@v5
94+
with:
95+
python-version: '3.13'
96+
97+
- name: Build mkdocs into apps/ui/public/docs (Issue #1021 / Epic #1026)
98+
shell: bash
99+
env:
100+
# Pip install only when the requirements file exists so the workflow
101+
# is forward-compatible with branches that have not yet pinned mkdocs.
102+
PYTHONUNBUFFERED: '1'
103+
# `--strict` is the eventual contract per #1021; today the docs
104+
# subtree has ~130 pre-existing link warnings inherited from
105+
# earlier editorial passes. Strict mode flips on once those clear
106+
# zero — tracked under issue #1021 acceptance criteria final pass.
107+
MKDOCS_STRICT: ${{ vars.MKDOCS_STRICT_BUILD || 'false' }}
108+
run: |
109+
set -euo pipefail
110+
if [ ! -f "mkdocs/requirements.txt" ]; then
111+
echo "mkdocs/requirements.txt not present; skipping docs build." >&2
112+
exit 0
113+
fi
114+
python -m pip install --upgrade pip
115+
python -m pip install -r mkdocs/requirements.txt
116+
STRICT_FLAG=""
117+
if [ "$MKDOCS_STRICT" = "true" ]; then
118+
STRICT_FLAG="--strict"
119+
fi
120+
(cd mkdocs && python -m mkdocs build ${STRICT_FLAG} --site-dir ../apps/ui/public/docs)
121+
test -f apps/ui/public/docs/index.html
122+
echo "mkdocs site emitted to apps/ui/public/docs/"
123+
92124
- name: Resolve and validate API URL
93125
id: api
94126
shell: bash

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -498,6 +498,8 @@ htmlcov/
498498

499499
# MkDocs build output
500500
mkdocs/site/
501+
# Generated mkdocs sub-site mounted under SWA at /docs/* (Issue #1021 / Epic #1026).
502+
apps/ui/public/docs/
501503

502504
# Archive files
503505
*.zip

‎apps/ui/app/sitemap.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,18 +33,96 @@ export default function sitemap(): MetadataRoute.Sitemap {
3333
changeFrequency: 'weekly',
3434
priority: 0.9,
3535
},
36+
{
37+
url: `${base}/retailers/value`,
38+
lastModified,
39+
changeFrequency: 'monthly',
40+
priority: 0.7,
41+
},
42+
{
43+
url: `${base}/retailers/agents`,
44+
lastModified,
45+
changeFrequency: 'monthly',
46+
priority: 0.7,
47+
},
48+
{
49+
url: `${base}/retailers/roi`,
50+
lastModified,
51+
changeFrequency: 'monthly',
52+
priority: 0.7,
53+
},
54+
{
55+
url: `${base}/retailers/comparators`,
56+
lastModified,
57+
changeFrequency: 'monthly',
58+
priority: 0.7,
59+
},
60+
{
61+
url: `${base}/retailers/case-studies`,
62+
lastModified,
63+
changeFrequency: 'monthly',
64+
priority: 0.6,
65+
},
66+
{
67+
url: `${base}/retailers/security`,
68+
lastModified,
69+
changeFrequency: 'monthly',
70+
priority: 0.7,
71+
},
3672
{
3773
url: `${base}/builders`,
3874
lastModified,
3975
changeFrequency: 'weekly',
4076
priority: 0.9,
4177
},
78+
{
79+
url: `${base}/builders/architecture`,
80+
lastModified,
81+
changeFrequency: 'monthly',
82+
priority: 0.7,
83+
},
84+
{
85+
url: `${base}/builders/adrs`,
86+
lastModified,
87+
changeFrequency: 'monthly',
88+
priority: 0.7,
89+
},
90+
{
91+
url: `${base}/builders/patterns`,
92+
lastModified,
93+
changeFrequency: 'monthly',
94+
priority: 0.7,
95+
},
96+
{
97+
url: `${base}/builders/telemetry`,
98+
lastModified,
99+
changeFrequency: 'monthly',
100+
priority: 0.6,
101+
},
42102
{
43103
url: `${base}/deploy`,
44104
lastModified,
45105
changeFrequency: 'monthly',
46106
priority: 0.8,
47107
},
108+
{
109+
url: `${base}/deploy/catalog`,
110+
lastModified,
111+
changeFrequency: 'monthly',
112+
priority: 0.7,
113+
},
114+
{
115+
url: `${base}/deploy/configure`,
116+
lastModified,
117+
changeFrequency: 'monthly',
118+
priority: 0.7,
119+
},
120+
{
121+
url: `${base}/deploy/preflight`,
122+
lastModified,
123+
changeFrequency: 'monthly',
124+
priority: 0.6,
125+
},
48126
{
49127
// Cross-reference to the mkdocs sitemap. Search engines follow nested
50128
// sitemap pointers; we don't duplicate the URLs.

‎apps/ui/components/molecules/ReadTheDocsCta.tsx‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
import type { ReactElement } from 'react';
2+
import Link from 'next/link';
3+
4+
/**
5+
* ReadTheDocsCta — bottom-of-page link from a value/pattern page to the
6+
* canonical mkdocs deep page (Issue #1025 / Epic #1026).
7+
*
8+
* Pattern: every value page on `/retailers/*` and pattern page on
9+
* `/builders/*` ends with a "Read the docs" CTA referencing the mkdocs
10+
* page that holds the deep treatment. The CTA is opt-in per page; pages
11+
* with no canonical doc just don't render it.
12+
*
13+
* `docsHref` is a SAME-DOMAIN absolute path under `/docs/`; `mkdocs` is
14+
* mounted as a sub-path so we never leave the SWA host.
15+
*/
16+
17+
export type ReadTheDocsCtaProps = {
18+
docsHref: string;
19+
/** Display label, e.g., "Read the architecture overview". */
20+
label: string;
21+
/** Optional second-line context. */
22+
caption?: string;
23+
testId?: string;
24+
};
25+
26+
const SECTION_STYLE = {
27+
display: 'flex',
28+
flexDirection: 'column' as const,
29+
alignItems: 'flex-start',
30+
gap: '0.375rem',
31+
padding: 'clamp(1.25rem, 3vw, 2rem) 1.5rem',
32+
background: 'var(--sys-surface-base, var(--hp-bg))',
33+
borderRadius: 'var(--radius-lg, 1rem)',
34+
border: '1px dashed var(--sys-border, var(--hp-border))',
35+
maxWidth: '52rem',
36+
margin: '0 auto',
37+
width: '100%',
38+
};
39+
40+
const LABEL_STYLE = {
41+
display: 'inline-flex',
42+
alignItems: 'center',
43+
gap: '0.5rem',
44+
padding: '0.5rem 1rem',
45+
borderRadius: 'var(--radius-md, 0.5rem)',
46+
background: 'var(--sys-surface, var(--hp-surface))',
47+
border: '1px solid var(--sys-border, var(--hp-border))',
48+
color: 'var(--sys-text, var(--hp-text))',
49+
fontWeight: 600,
50+
textDecoration: 'none' as const,
51+
fontSize: '0.9375rem',
52+
};
53+
54+
const CAPTION_STYLE = {
55+
fontSize: '0.8125rem',
56+
color: 'var(--sys-text-muted, var(--hp-text-muted))',
57+
};
58+
59+
export function ReadTheDocsCta({
60+
docsHref,
61+
label,
62+
caption,
63+
testId,
64+
}: ReadTheDocsCtaProps): ReactElement {
65+
return (
66+
<aside data-testid={testId} data-read-the-docs style={SECTION_STYLE}>
67+
<Link href={docsHref} style={LABEL_STYLE} data-docs-href={docsHref}>
68+
<span aria-hidden="true">📘</span>
69+
<span>{label}</span>
70+
</Link>
71+
{caption ? <p style={CAPTION_STYLE}>{caption}</p> : null}
72+
</aside>
73+
);
74+
}

‎apps/ui/components/molecules/TryThisInTheAppCta.tsx‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import type { ReactElement } from 'react';
2+
import Link from 'next/link';
3+
4+
/**
5+
* TryThisInTheAppCta — link from a docs page back to the live app surface
6+
* (Issue #1024 / Epic #1026).
7+
*
8+
* Renders inside markdown via the docs build (mkdocs/overrides/) when a
9+
* page declares `try_link:` front-matter. On the SWA the doc subtree is
10+
* mounted under `/docs/`, so the `appHref` resolves on the same origin.
11+
*
12+
* The component itself is just a primitive consumed in two places:
13+
* 1. mkdocs Material override that injects the CTA at the bottom of any
14+
* doc page with `try_link:` front-matter.
15+
* 2. SWA app pages that want to surface a "try this" affordance.
16+
*
17+
* This is the React side; the mkdocs Material override for the markdown
18+
* side lives in `mkdocs/overrides/`.
19+
*/
20+
21+
export type TryThisInTheAppCtaProps = {
22+
appHref: string;
23+
/** Display label, e.g., "Try the deploy portal". */
24+
label: string;
25+
/** Optional second-line context. */
26+
caption?: string;
27+
testId?: string;
28+
};
29+
30+
const SECTION_STYLE = {
31+
display: 'flex',
32+
flexDirection: 'column' as const,
33+
alignItems: 'flex-start',
34+
gap: '0.375rem',
35+
padding: 'clamp(1.25rem, 3vw, 2rem) 1.5rem',
36+
background: 'var(--sys-surface-accent, var(--hp-primary-soft))',
37+
borderRadius: 'var(--radius-lg, 1rem)',
38+
maxWidth: '52rem',
39+
margin: '0 auto',
40+
width: '100%',
41+
};
42+
43+
const LABEL_STYLE = {
44+
display: 'inline-flex',
45+
alignItems: 'center',
46+
gap: '0.5rem',
47+
padding: '0.5rem 1rem',
48+
borderRadius: 'var(--radius-md, 0.5rem)',
49+
background: 'var(--sys-action-primary, var(--hp-primary))',
50+
color: 'var(--sys-action-primary-foreground, white)',
51+
fontWeight: 600,
52+
textDecoration: 'none' as const,
53+
fontSize: '0.9375rem',
54+
};
55+
56+
const CAPTION_STYLE = {
57+
fontSize: '0.8125rem',
58+
color: 'var(--sys-text-muted, var(--hp-text-muted))',
59+
};
60+
61+
export function TryThisInTheAppCta({
62+
appHref,
63+
label,
64+
caption,
65+
testId,
66+
}: TryThisInTheAppCtaProps): ReactElement {
67+
return (
68+
<aside data-testid={testId} data-try-this-in-the-app style={SECTION_STYLE}>
69+
<Link href={appHref} style={LABEL_STYLE} data-app-href={appHref}>
70+
<span aria-hidden="true">▶︎</span>
71+
<span>{label}</span>
72+
</Link>
73+
{caption ? <p style={CAPTION_STYLE}>{caption}</p> : null}
74+
</aside>
75+
);
76+
}

‎apps/ui/public/staticwebapp.config.json‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
11
{
2-
"routes": []
2+
"routes": [
3+
{
4+
"route": "/docs/*",
5+
"headers": {
6+
"cache-control": "public, max-age=600"
7+
}
8+
}
9+
],
10+
"navigationFallback": {
11+
"rewrite": "/index.html",
12+
"exclude": [
13+
"/docs/*",
14+
"/_next/*",
15+
"/api/*",
16+
"/*.{png,jpg,jpeg,svg,ico,webp,gif,css,js,json,txt,xml,woff,woff2,map,wasm,pdf}"
17+
]
18+
}
319
}

‎apps/ui/staticwebapp.config.json‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,19 @@
11
{
2-
"routes": []
2+
"routes": [
3+
{
4+
"route": "/docs/*",
5+
"headers": {
6+
"cache-control": "public, max-age=600"
7+
}
8+
}
9+
],
10+
"navigationFallback": {
11+
"rewrite": "/index.html",
12+
"exclude": [
13+
"/docs/*",
14+
"/_next/*",
15+
"/api/*",
16+
"/*.{png,jpg,jpeg,svg,ico,webp,gif,css,js,json,txt,xml,woff,woff2,map,wasm,pdf}"
17+
]
18+
}
319
}

0 commit comments

Comments
 (0)