Skip to content

Commit c1e49e1

Browse files
paulczarpaulczar
authored
rosa cost explorer (#959)
* rosa cost explorer Signed-off-by: Paul Czarkowski <username.taken@gmail.com> * add spot for karpenter and % of burst in use Signed-off-by: Paul Czarkowski <username.taken@gmail.com> * update app to have expandable sections, set baseline Signed-off-by: Paul Czarkowski <username.taken@gmail.com> * add clarifications around run rate Signed-off-by: Paul Czarkowski <username.taken@gmail.com> * lots of improvements Signed-off-by: Paul Czarkowski <username.taken@gmail.com> * fix mcneils feedback Signed-off-by: Paul Czarkowski <username.taken@gmail.com> --------- Signed-off-by: Paul Czarkowski <username.taken@gmail.com>
1 parent 5799d44 commit c1e49e1

7 files changed

Lines changed: 1967 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,120 @@ When inline Markdown or shortcodes support it, Hugo `ref` / `relref` (or other t
7575
- **Do not** change `themes/rhds` for content-only tasks.
7676
- Layout or theme edits affect every page; keep them minimal, reversible, and consistent with RHDS patterns (`rh-alert`, etc.).
7777

78+
## Standalone app pages (`assets/` + custom layout)
79+
80+
Use this pattern for **full-page interactive tools** (Vue apps, calculators, dashboards) that need complete control over HTML, CSS, and JS while still sharing site header, nav, footer, cookie consent, and Pagefind search with the rest of the docs.
81+
82+
**Reference implementation:** [ROSA Fleet Optimizer](content/rosa/cost-explorer/index.md)
83+
84+
| Piece | Path | Role |
85+
|-------|------|------|
86+
| Hugo content stub | `content/<section>/<name>/index.md` | Front matter only; sets `layout:` and metadata (`title`, `tags`, `authors`, etc.). Body is empty or omitted. |
87+
| App source (HTML) | `assets/<section>/<name>/app.html` | Full `<!DOCTYPE html>` document: page markup, inline styles, and scripts. Uses **placeholders** where Hugo injects shared chrome at build time. |
88+
| Layout | `layouts/_default/<layout-name>.html` | Loads the asset via `resources.Get`, replaces placeholders, outputs with `safeHTML` (bypasses `baseof`). |
89+
| Shared partials | `layouts/partials/rhds/` | Header, nav, footer, Pagefind init (do **not** copy these into `app.html`). |
90+
91+
### Why `assets/` and not `content/` or `static/`?
92+
93+
- **`content/`** is for Markdown guides processed by Goldmark. Large Vue/HTML apps do not belong in the body.
94+
- **`static/`** copies files verbatim with no Hugo templating; you cannot inject partials or fingerprint CSS.
95+
- **`assets/`** files are available to layouts via `resources.Get` and can be transformed (string replace, pipe to other resources) at build time.
96+
97+
### Placeholders (contract between `app.html` and layout)
98+
99+
The app HTML must include these literal tokens; the layout replaces them before publish:
100+
101+
| Token | Injected by layout | Purpose |
102+
|-------|-------------------|---------|
103+
| `__TRACKING_HEAD__` | `partial "head/tracking.html"` | TrustArc / analytics scripts (cookie consent bootstrap). |
104+
| `__MAIN_CSS__` | Fingerprinted `resources.Get "css/main.css"` href | Site-wide RHDS styles (header search, nav, typography tokens). |
105+
| `__HEADER__` | `partial "rhds/header.html"` | Logo + Pagefind search mount (`#site-search`). |
106+
| `__NAV__` | `partial "rhds/nav.html"` | Sticky `rh-navigation-secondary` nav. |
107+
| `__FOOTER__` | `partial "rhds/footer.html"` | RHDS footer, `#teconsent`, and `#consent_blackbar`. |
108+
| `__PAGEFIND_INIT__` | `partial "rhds/pagefind-init.html"` | Pagefind UI init + header search drawer behavior. |
109+
110+
Put `__TRACKING_HEAD__` in `<head>`. Put `__HEADER__` and `__NAV__` immediately after `<body>`. Put `__FOOTER__` and `__PAGEFIND_INIT__` after your app’s closing `</main>` (or equivalent), before app-specific scripts if those scripts must run after DOM chrome exists.
111+
112+
**Do not** duplicate header, nav, footer, consent markup, or Pagefind init JS in `app.html`. When site chrome is fixed in partials, all standalone apps pick up the change on the next build.
113+
114+
### Layout template (minimal pattern)
115+
116+
Copy [`layouts/_default/cost-explorer-app.html`](./layouts/_default/cost-explorer-app.html) and adjust the asset path and error message:
117+
118+
```go-html-template
119+
{{- $css := resources.Get "css/main.css" -}}
120+
{{- $cssHref := "/experts/css/main.css" -}}
121+
{{- if hugo.IsProduction -}}
122+
{{- with $css | minify | fingerprint -}}
123+
{{- $cssHref = .RelPermalink -}}
124+
{{- end -}}
125+
{{- else -}}
126+
{{- with $css -}}
127+
{{- $cssHref = .RelPermalink -}}
128+
{{- end -}}
129+
{{- end -}}
130+
{{- $tracking := partial "head/tracking.html" . -}}
131+
{{- $app := resources.Get "section/name/app.html" -}}
132+
{{- if not $app -}}
133+
{{- errorf "My App: assets/section/name/app.html not found" -}}
134+
{{- end -}}
135+
{{- $html := replace $app.Content "__MAIN_CSS__" $cssHref -}}
136+
{{- $html = replace $html "__TRACKING_HEAD__" $tracking -}}
137+
{{- $html = replace $html "__HEADER__" (partial "rhds/header.html" .) -}}
138+
{{- $html = replace $html "__NAV__" (partial "rhds/nav.html" .) -}}
139+
{{- $html = replace $html "__FOOTER__" (partial "rhds/footer.html" .) -}}
140+
{{- $html = replace $html "__PAGEFIND_INIT__" (partial "rhds/pagefind-init.html" .) -}}
141+
{{ $html | safeHTML }}
142+
```
143+
144+
Front matter in `content/.../index.md`:
145+
146+
```yaml
147+
---
148+
title: "My Tool"
149+
description: "Short summary for listings and SEO."
150+
date: 2026-06-25
151+
tags: ["ROSA"]
152+
authors:
153+
- Name
154+
layout: my-app # matches layouts/_default/my-app.html
155+
---
156+
```
157+
158+
Layout file name must match the `layout` front-matter value (`my-app` → `my-app.html`).
159+
160+
### `app.html` checklist
161+
162+
- Full HTML document with RHDS import map and module imports for web components you use (`rh-navigation-secondary`, `rh-footer`, etc.). See the Fleet Optimizer head for a working set.
163+
- Link `__MAIN_CSS__`, `/experts/pagefind/pagefind-ui.css`, and RHDS element lightdom CSS URLs for nav/footer.
164+
- Wrap tool UI in `<main class="…">` (class name is app-specific).
165+
- Same-site links and static assets use **`/experts/...`** root-relative paths.
166+
- Modals, popovers, and overlays: **`teleport` to `body`** (if using Vue) and use **`z-index` ≥ 1000** so they sit above the site header (`z-index: 200`) and cookie consent bar.
167+
- Prefer **native `<details>` / `<summary>`** over the theme `expand` shortcode (jQuery not loaded on these pages).
168+
- No em dashes in user-facing copy inside the app.
169+
170+
### Pagefind and search indexing
171+
172+
The injected header expects `#site-search`. Include `pagefind-ui.css` in `<head>` and `__PAGEFIND_INIT__` before your app scripts.
173+
174+
Standalone app pages use a **custom layout**, not `baseof`, so they do **not** get `data-pagefind-body` on `<main>` unless you add it yourself. Most tools should stay **out of the search index**; do not add `data-pagefind-body` unless the page should appear in site search.
175+
176+
### Verification
177+
178+
After adding or changing a standalone app:
179+
180+
```bash
181+
hugo --gc --minify --theme rhds
182+
```
183+
184+
Confirm in `public/experts/<section>/<name>/index.html`:
185+
186+
- No unreplaced `__HEADER__`-style tokens remain.
187+
- `#consent_blackbar`, `#teconsent`, and `site-header__search` are present.
188+
- Header search opens and respects viewport height (Pagefind drawer).
189+
190+
Smoke-check in the browser: header, nav, footer, cookie consent, modals, and app functionality.
191+
78192
## Verification / testing (before claiming a change works)
79193

80194
Run these from the repository root after substantive edits:

0 commit comments

Comments
 (0)