diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 4553e686..a07137d9 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -11,8 +11,27 @@ permissions: contents: read jobs: + renderer-tests: + name: Test Dev Notes renderer (Python ${{ matrix.python-version }}) + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ["3.10", "3.12"] + steps: + - name: Checkout + uses: actions/checkout@v7 + + - name: Set up Python + uses: actions/setup-python@v6 + with: + python-version: ${{ matrix.python-version }} + + - name: Run renderer tests + run: python -m unittest discover -s tests + validate: name: Validate documentation + needs: renderer-tests runs-on: ubuntu-latest steps: - name: Checkout @@ -28,9 +47,15 @@ jobs: - name: Check Dev Notes renderer syntax run: python -m py_compile scripts/render-dev-notes.py + - name: Check navigation JavaScript syntax + run: node --check docs/javascripts/navigation-drawer.js + - name: Build documentation run: scripts/build-docs.sh + - name: Verify generated documentation is committed + run: git diff --exit-code -- docs/dev-notes zensical.toml + deploy: name: Deploy documentation if: >- diff --git a/AGENTS.md b/AGENTS.md index 25ab4d70..6009786f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -46,8 +46,10 @@ explicit `url` or `avatar` fields when needed. Each Dev Note post needs `title`, `date`, `description`, and at least one author. The landing card uses `description` as its summary, `categories[0]` as the topic after `Dev Note`, and `card_tags` when present; otherwise it falls -back to `tags`. `card_variant` is optional and maps to a CSS modifier such as -`.dev-note-card--launch`. +back to `tags`. Dates must use the exact `YYYY-MM-DD` form. `card_variant` is +optional and maps to both the card and artwork CSS modifiers, such as +`.dev-note-card--launch` and `.dev-note-card__visual--launch`; add the +corresponding styles when introducing a new visual variant. Posts are sorted newest first by ISO `date`, then title. Use dated filenames such as `YYYY-MM-DD-short-title.md` so file paths stay stable and readable, but diff --git a/README.md b/README.md index d30c3344..975d3800 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ OpenShell as the runtime. - `docs/dev-notes/` contains research engineering updates, release notes, and build logs worth sharing. - `docs/dev-notes/authors.json` contains reusable Dev Notes author metadata. +- `docs/documentation/` contains durable guides and references for packages, + libraries, benchmarks, and examples introduced in Dev Notes. - `projects/` contains self-contained research projects and a reusable Python project template. - `scripts/render-dev-notes.py` renders Dev Notes cards, post bylines, and @@ -31,6 +33,7 @@ To preview the documentation locally: python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements-docs.txt +python scripts/render-dev-notes.py zensical serve ``` @@ -55,14 +58,22 @@ after validation passes. Add new posts under `docs/dev-notes/posts/` with a dated filename such as `YYYY-MM-DD-short-title.md`. Set `authors` to IDs from `docs/dev-notes/authors.json`; add new authors there once, including their -GitHub handle and description. Run `python scripts/render-dev-notes.py` after -editing posts or authors so the landing-page cards, visible post bylines, and -Dev Notes navigation stay in sync. +GitHub handle and description. Dates must use the exact `YYYY-MM-DD` form. +`card_tags` controls the landing-page taxonomy (falling back to `tags`), and an +optional `card_variant` selects a matching visual modifier such as `launch`. +Run `python scripts/render-dev-notes.py` after editing posts or authors so the +landing-page cards, visible post bylines, and Dev Notes navigation stay in +sync; CI verifies that generated changes are committed. + +### Documentation + +Add durable software documentation under `docs/documentation/` when a Dev Note +introduces a package, library, benchmark, or reusable example. Link the +documentation back to its originating Dev Note and cover installation, usage, +reproducibility requirements, and known limitations. Add the new page beneath +the `Documentation` entry in `zensical.toml`. ## Content model -Use the documentation for durable project knowledge: architecture notes, -application guides, runtime integration details, and reproducible research -engineering workflows. Use Dev Notes for dated updates: experiments, milestones, -benchmarks, release notes, and lessons learned while turning research into OpenShell -applications. +Use Documentation for durable software knowledge. Use Dev Notes for dated +experiments, benchmarks, releases, use case examples, and engineering updates. diff --git a/docs/dev-notes/index.md b/docs/dev-notes/index.md index 9f8f608a..138d67d3 100644 --- a/docs/dev-notes/index.md +++ b/docs/dev-notes/index.md @@ -1,57 +1,108 @@ --- title: Dev Notes -description: Dated engineering notes, experiments, milestones, and lessons from building OpenShell research applications. +description: Research field notes, experiments, milestones, and lessons from building OpenShell research applications. hide: - toc --- -# Dev Notes - -
-
- - OpenShell Research -
-
-

Research-to-runtime field notes

-

- What changed, - what worked, - and what we learned. -

-

- Dev Notes are the dated engineering record for OpenShell Research: build - logs, experiment results, runtime discoveries, release notes, and the - useful mistakes that should not have to be rediscovered. -

-
-
+
+
+
+ + + OpenShell Research / Dev Notes + +
+
+
+

Dev Notes

+

+ Technical notes from the OpenShell team – reproducible research, + benchmarks, and use case examples. +

+
+
+
-
- - -
+
+
+ + Latest from the team +
+ +
+
+
+

Recent notes

+ The working archive +
+
+ +
+
+ + +
diff --git a/docs/dev-notes/posts/2026-06-04-bootstrapping-openshell-research.md b/docs/dev-notes/posts/2026-06-04-bootstrapping-openshell-research.md index b0303dd2..fd1121ee 100644 --- a/docs/dev-notes/posts/2026-06-04-bootstrapping-openshell-research.md +++ b/docs/dev-notes/posts/2026-06-04-bootstrapping-openshell-research.md @@ -24,9 +24,13 @@ card_tags: -
-

Authors

-
+
+

+ Field note + + Runtime +

+
diff --git a/docs/dev-notes/posts/2026-06-05-making-dev-notes-repeatable.md b/docs/dev-notes/posts/2026-06-05-making-dev-notes-repeatable.md index 1db04693..7dfb71de 100644 --- a/docs/dev-notes/posts/2026-06-05-making-dev-notes-repeatable.md +++ b/docs/dev-notes/posts/2026-06-05-making-dev-notes-repeatable.md @@ -4,7 +4,7 @@ date: 2026-06-05 updated: 2026-06-05 description: A repeatable author and post workflow keeps Dev Notes easy to extend as the research log grows. categories: - - Documentation + - Process tags: - dev-notes - authors @@ -21,9 +21,13 @@ card_tags: -
-

Author

-
+
+

+ Field note + + Process +

+
diff --git a/docs/documentation/index.md b/docs/documentation/index.md new file mode 100644 index 00000000..400e3484 --- /dev/null +++ b/docs/documentation/index.md @@ -0,0 +1,12 @@ +--- +title: Documentation +description: Guides and reference material for software introduced in OpenShell Dev Notes. +--- + +# Documentation + +Guides and reference material for packages, libraries, benchmarks, and examples +introduced in OpenShell Dev Notes will be published here. + +Each documentation page will link to the Dev Note that introduced the work and +cover installation, usage, reproducibility requirements, and known limitations. diff --git a/docs/index.md b/docs/index.md index 62f67664..f7a8dfa9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,30 +1,32 @@ -# OpenShell Research +--- +title: OpenShell Research +description: Dev Notes and software documentation from the OpenShell team. +hide: + - toc +--- -
-
- - OpenShell Research -
-

Research engineering documentation

-

- OpenShell Research turns new research into usable applications that run on - the OpenShell runtime. This site collects the engineering record: what we - are building, how the runtime is used, and what we learn from each - experiment. -

-
+
+
+
+

+ + OpenShell Research +

+
+
-## Starting points - -- [Research engineering](research/index.md) -- [Runtime notes](research/runtime.md) -- [Application skeletons](research/applications.md) -- [Dev Notes](dev-notes/index.md) - -## What belongs here - -- OpenShell runtime integration notes -- Experimental application designs -- Research-to-product build logs -- Benchmarks, evaluations, and reproducibility notes -- Deployment and sharing patterns for research applications + +
diff --git a/docs/javascripts/navigation-drawer.js b/docs/javascripts/navigation-drawer.js new file mode 100644 index 00000000..83ebaea0 --- /dev/null +++ b/docs/javascripts/navigation-drawer.js @@ -0,0 +1,169 @@ +(() => { + let cleanup = () => {}; + + function enhanceNavigationDrawer() { + cleanup(); + + const toggle = document.querySelector("#__drawer"); + const sidebar = document.querySelector(".md-sidebar--primary"); + const overlay = document.querySelector('.md-overlay[for="__drawer"]'); + const legacyControl = document.querySelector( + '.md-header__button[for="__drawer"]', + ); + + if (!(toggle instanceof HTMLInputElement) || !(sidebar instanceof HTMLElement)) { + cleanup = () => {}; + return; + } + + let button = document.querySelector(".openshell-drawer-button"); + if (!(button instanceof HTMLButtonElement) && legacyControl instanceof HTMLElement) { + button = document.createElement("button"); + button.type = "button"; + button.className = legacyControl.className; + button.classList.add("openshell-drawer-button"); + button.innerHTML = legacyControl.innerHTML; + legacyControl.replaceWith(button); + } + + if (!(button instanceof HTMLButtonElement)) { + cleanup = () => {}; + return; + } + + sidebar.id = "primary-navigation"; + sidebar.setAttribute("role", "dialog"); + sidebar.setAttribute("aria-label", "Primary navigation"); + button.setAttribute("aria-controls", sidebar.id); + + let returnFocus = button; + const backgroundElements = new Map(); + + const rememberBackgroundElement = (element) => { + if (element instanceof HTMLElement && element !== button && element !== sidebar) { + backgroundElements.set(element, element.inert); + } + }; + + Array.from(button.parentElement?.children ?? []).forEach(rememberBackgroundElement); + Array.from(sidebar.parentElement?.children ?? []).forEach(rememberBackgroundElement); + document + .querySelectorAll('[data-md-component="skip"], [data-md-component="announce"]') + .forEach(rememberBackgroundElement); + + const container = document.querySelector(".md-container"); + if (container instanceof HTMLElement) { + Array.from(container.children) + .filter((element) => !element.contains(sidebar)) + .forEach(rememberBackgroundElement); + } + + const focusableElements = () => + Array.from( + sidebar.querySelectorAll( + 'a[href], button:not([disabled]), input:not([disabled]), [tabindex]:not([tabindex="-1"])', + ), + ).filter((element) => element instanceof HTMLElement && !element.hidden); + + const synchronize = ({ moveFocus = false, restoreFocus = false } = {}) => { + const isOpen = toggle.checked; + button.setAttribute("aria-expanded", String(isOpen)); + button.setAttribute("aria-label", isOpen ? "Close navigation" : "Open navigation"); + sidebar.setAttribute("aria-hidden", String(!isOpen)); + if (isOpen) { + sidebar.setAttribute("aria-modal", "true"); + } else { + sidebar.removeAttribute("aria-modal"); + } + sidebar.inert = !isOpen; + backgroundElements.forEach((wasInert, element) => { + element.inert = isOpen || wasInert; + }); + + if (isOpen && moveFocus) { + focusableElements()[0]?.focus(); + } else if (!isOpen && restoreFocus) { + returnFocus.focus(); + } + }; + + const setOpen = (isOpen, options = {}) => { + if (isOpen) { + returnFocus = button; + } + toggle.checked = isOpen; + synchronize(options); + }; + + const onButtonClick = () => { + setOpen(!toggle.checked, { + moveFocus: !toggle.checked, + restoreFocus: toggle.checked, + }); + }; + + const onToggleChange = () => synchronize(); + const onOverlayClick = (event) => { + event.preventDefault(); + setOpen(false, { restoreFocus: true }); + }; + const onSidebarClick = (event) => { + if (event.target instanceof Element && event.target.closest("a[href]")) { + setOpen(false); + } + }; + const onKeyDown = (event) => { + if (!toggle.checked) return; + + if (event.key === "Escape") { + event.preventDefault(); + setOpen(false, { restoreFocus: true }); + return; + } + + if (event.key !== "Tab") return; + + const focusable = focusableElements(); + if (!focusable.length) { + event.preventDefault(); + return; + } + + const first = focusable[0]; + const last = focusable[focusable.length - 1]; + if (event.shiftKey && document.activeElement === first) { + event.preventDefault(); + last.focus(); + } else if (!event.shiftKey && document.activeElement === last) { + event.preventDefault(); + first.focus(); + } + }; + + button.addEventListener("click", onButtonClick); + toggle.addEventListener("change", onToggleChange); + overlay?.addEventListener("click", onOverlayClick); + sidebar.addEventListener("click", onSidebarClick); + document.addEventListener("keydown", onKeyDown); + synchronize(); + + cleanup = () => { + button.removeEventListener("click", onButtonClick); + toggle.removeEventListener("change", onToggleChange); + overlay?.removeEventListener("click", onOverlayClick); + sidebar.removeEventListener("click", onSidebarClick); + document.removeEventListener("keydown", onKeyDown); + backgroundElements.forEach((wasInert, element) => { + element.inert = wasInert; + }); + }; + } + + if (window.document$?.subscribe) { + window.document$.subscribe(enhanceNavigationDrawer); + } else if (document.readyState === "loading") { + document.addEventListener("DOMContentLoaded", enhanceNavigationDrawer, { once: true }); + } else { + enhanceNavigationDrawer(); + } +})(); diff --git a/docs/research/applications.md b/docs/research/applications.md index d761fb70..0fd92a73 100644 --- a/docs/research/applications.md +++ b/docs/research/applications.md @@ -1,20 +1,12 @@ -# Application Skeletons +--- +title: Application documentation has moved +hide: + - toc +--- -This page will track the starter patterns we use to move research ideas into -OpenShell applications. + -## Candidate skeletons +# Application documentation has moved -- Agent workflow demo -- Research paper companion -- Evaluation harness -- Interactive dataset explorer -- Model capability probe - -## Skeleton checklist - -- Clear user workflow -- Minimal runtime integration -- Reproducible setup -- Observable behavior -- Documented limitations +Application guides and examples now live in +[Documentation](../documentation/). diff --git a/docs/research/index.md b/docs/research/index.md index 5ffee4f0..ea211f55 100644 --- a/docs/research/index.md +++ b/docs/research/index.md @@ -1,18 +1,11 @@ -# Research Engineering +--- +title: Research documentation has moved +hide: + - toc +--- -This section is for durable engineering documentation that should outlive a -single experiment or Dev Note. + -## Working areas +# Research documentation has moved -- Runtime integration: how applications bind to OpenShell. -- Application patterns: reusable structures for research prototypes. -- Evaluation: benchmarks, qualitative checks, and reproducibility criteria. -- Distribution: packaging and sharing completed research applications. - -## Initial standards - -- Prefer small, reproducible examples over broad claims. -- Capture environment assumptions with every experiment. -- Link Dev Notes updates back to the durable docs page they inform. -- Promote repeated patterns into templates only after they are used twice. +This material now lives in [Documentation](../documentation/). diff --git a/docs/research/runtime.md b/docs/research/runtime.md index 4ae47c9d..96d42a16 100644 --- a/docs/research/runtime.md +++ b/docs/research/runtime.md @@ -1,18 +1,12 @@ -# OpenShell Runtime Notes +--- +title: Runtime documentation has moved +hide: + - toc +--- -Use this page to document how research applications use OpenShell as their -runtime. + -## Topics to fill in +# Runtime documentation has moved -- Runtime capabilities and constraints -- Application lifecycle -- Data and model access patterns -- Observability and debugging -- Packaging and deployment expectations - -## Open questions - -- Which runtime APIs should every example application demonstrate? -- What is the minimum viable application shape for a research prototype? -- Which runtime assumptions need automated checks in CI? +Runtime guides and reference material now live in +[Documentation](../documentation/). diff --git a/docs/stylesheets/dev-notes.css b/docs/stylesheets/dev-notes.css index 844f7653..f5956783 100644 --- a/docs/stylesheets/dev-notes.css +++ b/docs/stylesheets/dev-notes.css @@ -1,379 +1,1082 @@ /* SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. */ /* SPDX-License-Identifier: Apache-2.0 */ +/* + * OpenShell Research uses the structure of an academic field journal: warm + * paper, typographic hierarchy, precise rules, and small technical signals. + * The display face is deliberately system-native so the site remains fast and + * private while still feeling more literary than a typical documentation UI. + */ + :root { --openshell-green: #76b900; - --openshell-ink: #18181a; - --openshell-ink-soft: #242529; - --openshell-paper: #f7faf3; - --openshell-home-hero-bg: - linear-gradient(135deg, #fff 0%, var(--openshell-paper) 62%, #eef7e4 100%), - var(--md-default-bg-color); - --openshell-home-hero-border: color-mix(in srgb, var(--md-default-fg-color) 14%, transparent); - --openshell-home-brand-color: var(--openshell-ink); - --openshell-card-bg: - linear-gradient(180deg, rgba(255, 255, 255, 0.05), transparent), - var(--md-default-bg-color); - --openshell-card-shadow: 0 0.55rem 1.6rem rgba(15, 23, 42, 0.11); - --md-primary-fg-color: var(--openshell-ink); - --md-primary-fg-color--light: #2b2c31; - --md-primary-fg-color--dark: #0f1012; - --md-accent-fg-color: var(--openshell-green); - --md-accent-fg-color--transparent: rgba(118, 185, 0, 0.16); + --openshell-green-soft: #8dc63f; + --openshell-accent: #3c626b; + --openshell-accent-soft: #71878a; + --openshell-diagram: #78918e; + --openshell-diagram-bright: #b9cbc7; + --openshell-ink: #202625; + --openshell-ink-soft: #303938; + --openshell-paper: #f3f0e7; + --openshell-paper-raised: #faf8f1; + --openshell-paper-deep: #e7e2d6; + --openshell-muted: #666d6b; + --openshell-rule: rgba(32, 38, 37, 0.2); + --openshell-rule-strong: rgba(32, 38, 37, 0.54); + --openshell-serif: "Iowan Old Style", "Palatino Linotype", "Book Antiqua", Palatino, Georgia, serif; + --openshell-sans: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; + --openshell-mono: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace; + --md-default-bg-color: var(--openshell-paper); + --md-default-fg-color: var(--openshell-ink); + --md-primary-fg-color: var(--openshell-paper-raised); + --md-primary-fg-color--light: var(--openshell-paper); + --md-primary-fg-color--dark: var(--openshell-paper-deep); + --md-primary-bg-color: var(--openshell-ink); + --md-accent-fg-color: #294f58; + --md-accent-fg-color--transparent: rgba(60, 98, 107, 0.14); + --md-typeset-a-color: var(--openshell-accent); +} + +body[data-md-color-scheme="slate"] { + --openshell-accent: #a8c1c5; + --openshell-accent-soft: #82999c; + --openshell-diagram: #91aaa7; + --openshell-diagram-bright: #c6d5d2; + --openshell-ink: #e6e8e2; + --openshell-ink-soft: #c7cecb; + --openshell-paper: #121719; + --openshell-paper-raised: #181e20; + --openshell-paper-deep: #222a2c; + --openshell-muted: #9fa8a5; + --openshell-rule: rgba(230, 232, 226, 0.17); + --openshell-rule-strong: rgba(230, 232, 226, 0.43); + --md-default-bg-color: var(--openshell-paper); + --md-default-fg-color: var(--openshell-ink); + --md-primary-fg-color: var(--openshell-paper-raised); + --md-primary-fg-color--light: var(--openshell-paper); + --md-primary-fg-color--dark: #0c1011; + --md-primary-bg-color: var(--openshell-ink); + --md-accent-fg-color: #bdd0d3; + --md-accent-fg-color--transparent: rgba(168, 193, 197, 0.16); + --md-typeset-a-color: var(--openshell-accent); } body[data-md-color-scheme="default"][data-md-color-primary="black"] { - --md-typeset-a-color: #356f00; + --md-typeset-a-color: var(--openshell-accent); } body[data-md-color-scheme="slate"][data-md-color-primary="black"] { - --md-primary-fg-color: var(--openshell-ink); - --md-primary-fg-color--light: #2b2c31; - --md-primary-fg-color--dark: #0f1012; - --md-accent-fg-color: var(--openshell-green); - --md-accent-fg-color--transparent: rgba(118, 185, 0, 0.18); - --md-typeset-a-color: #9bdc49; - --openshell-home-hero-bg: - linear-gradient(135deg, #1c1d20 0%, #161a14 58%, #15240d 100%), - var(--md-default-bg-color); - --openshell-home-hero-border: rgba(255, 255, 255, 0.12); - --openshell-home-brand-color: #fff; - --openshell-card-bg: - linear-gradient(180deg, rgba(118, 185, 0, 0.06), transparent), - color-mix(in srgb, var(--md-default-bg-color) 94%, var(--openshell-green)); - --openshell-card-shadow: 0 0.55rem 1.6rem rgba(0, 0, 0, 0.28); + --md-typeset-a-color: var(--openshell-accent); +} + +html { + scroll-behavior: smooth; +} + +body { + background: var(--openshell-paper); + font-family: var(--openshell-sans); +} + +::selection { + background: color-mix(in srgb, var(--openshell-accent) 34%, var(--openshell-paper-raised)); + color: var(--openshell-ink); } .md-header { - background: var(--openshell-ink); - color: #fff; + border-bottom: 1px solid var(--openshell-rule); + background: color-mix(in srgb, var(--openshell-paper) 92%, transparent); + box-shadow: none; + color: var(--openshell-ink); + backdrop-filter: blur(18px); } -.md-header__button.md-logo { +.md-header__inner { + height: 3.7rem; +} + +.md-header__inner > [for="__drawer"], +.md-header__inner > .openshell-drawer-button { display: inline-flex; align-items: center; + justify-content: center; + order: -2; } -.md-header__title { - color: #fff; +.openshell-drawer-button:focus-visible { + border-radius: 0.2rem; + outline: 2px solid var(--openshell-accent); + outline-offset: 0.15rem; +} + +.md-header__inner > .md-logo { + order: -1; +} + +.md-header__button.md-logo { + display: none; } .md-header__button.md-logo img { - height: 1.35rem; - width: auto; + width: 1.7rem; + height: 1.7rem; +} + +.md-header__title { + color: var(--openshell-ink); + font-family: var(--openshell-serif); + font-size: 1.02rem; + font-weight: 600; + letter-spacing: -0.025em; +} + +.md-header__title .md-header__ellipsis { + visibility: hidden; } .md-header__source { display: none !important; } -.md-header .md-search__button { - background-color: rgba(255, 255, 255, 0.12); - color: rgba(255, 255, 255, 0.82); +.md-overlay { + position: fixed; + z-index: 4; + display: block; + background: rgba(12, 16, 17, 0.62); + inset: 0; + opacity: 0; + pointer-events: none; + transition: opacity 180ms ease; +} + +#__drawer:checked ~ .md-overlay { + opacity: 1; + pointer-events: auto; +} + +.md-sidebar--primary { + position: fixed !important; + z-index: 5; + top: 0.5rem !important; + bottom: auto !important; + left: 0.25rem !important; + display: block; + width: 15.25rem; + height: calc(100vh - 1rem) !important; + padding: 0; + border: 1px solid var(--openshell-rule); + border-radius: 0.5rem; + background: var(--openshell-paper-raised); + box-shadow: 0 1.2rem 3rem rgba(0, 0, 0, 0.2); + transform: translateX(calc(-100% - 0.5rem)) !important; + visibility: hidden; + transition: transform 200ms ease, visibility 0s linear 200ms !important; +} + +#__drawer:checked ~ .md-container .md-sidebar--primary { + transform: translateX(0) !important; + visibility: visible; + transition-delay: 0s !important; } -.md-header .md-search__button:focus, -.md-header .md-search__button:hover { - background-color: rgba(255, 255, 255, 0.18); - color: #fff; +.md-sidebar--primary .md-sidebar__scrollwrap { + height: 100%; + margin: 0; + overflow-y: auto; } -.md-header .md-search__button::before { - background-color: rgba(255, 255, 255, 0.78); +.md-sidebar--primary .md-sidebar__inner { + padding: 0.8rem; } -.md-header .md-search__button::after { - background: rgba(255, 255, 255, 0.9); +.md-sidebar--primary .md-nav--primary[data-md-level="0"] > .md-nav__title { + display: flex !important; + align-items: center; + gap: 0.75rem; + min-height: 3rem; + padding: 0.6rem 0.5rem 0.85rem; color: var(--openshell-ink); + font-family: var(--openshell-serif); + font-size: 0.9rem; + line-height: 1.2; } -.dev-notes-hero { - margin: 1rem 0 1.5rem; +.md-sidebar--primary .md-nav--primary[data-md-level="0"] > .md-nav__title .md-logo { + position: static; + width: 2rem; + height: 2rem; + margin: 0; + padding: 0; } -.openshell-home-hero { - margin: 1rem 0 1.8rem; - padding: clamp(1.15rem, 3.5vw, 2.1rem); - border: 1px solid var(--openshell-home-hero-border); - border-radius: 8px; - background: var(--openshell-home-hero-bg); +.md-sidebar--primary .md-nav--primary[data-md-level="0"] > .md-nav__title .md-logo img { + width: 2rem; + height: 2rem; } -.openshell-home-hero, -.openshell-home-hero *, -.dev-notes-hero, -.dev-notes-hero * { +.md-header .md-search__form { + border: 1px solid transparent; + border-radius: 999px; + background: color-mix(in srgb, var(--openshell-ink) 6%, transparent); +} + +.md-header .md-search__form:hover, +.md-header .md-search__form:focus-within { + border-color: var(--openshell-rule); + background: var(--openshell-paper-raised); +} + +.md-header .md-search__input, +.md-header .md-search__icon, +.md-header .md-search__button, +.md-header [for="__search"] { + color: var(--openshell-ink); +} + +.md-header .md-search__input::placeholder { + color: var(--openshell-muted); +} + +.md-header .md-search__options .md-icon, +.md-header .md-search__kbd { + color: var(--openshell-muted); +} + +.md-main { + background: + linear-gradient(90deg, transparent 0, transparent calc(50% - 36rem), color-mix(in srgb, var(--openshell-rule) 20%, transparent) calc(50% - 36rem), transparent calc(50% - 35.95rem)), + var(--openshell-paper); +} + +.md-main__inner { + margin-top: 1.7rem; +} + +.md-typeset { + color: var(--openshell-ink); + font-size: 0.8rem; + line-height: 1.75; +} + +.md-typeset h1, +.md-typeset h2, +.md-typeset h3 { + color: var(--openshell-ink); + font-family: var(--openshell-serif); + font-weight: 500; + letter-spacing: -0.035em; +} + +.md-typeset h1 { + font-size: clamp(2.25rem, 5vw, 3.8rem); + line-height: 1.02; +} + +.md-typeset h2 { + font-size: clamp(1.5rem, 3vw, 2.15rem); + line-height: 1.08; +} + +.md-typeset a { + text-decoration-thickness: 0.06em; + text-underline-offset: 0.16em; +} + +.md-nav { + font-size: 0.72rem; +} + +.md-nav__item .md-nav__link--active { + color: var(--md-typeset-a-color); + font-weight: 650; +} + +.md-footer { + border-top: 1px solid var(--openshell-rule); + background: var(--openshell-paper); +} + +.md-footer-meta { + background: var(--openshell-paper); + color: var(--openshell-muted); +} + +.md-footer-meta a { + color: inherit; +} + +/* Landing page ------------------------------------------------------------ */ + +body:has(.dev-notes-page) .md-grid, +body:has(.openshell-home-page) .md-grid { + max-width: 66rem; +} + +body:has(.dev-notes-page) .md-main__inner, +body:has(.openshell-home-page) .md-main__inner { + margin-top: 0; +} + +body:has(.dev-notes-page) .md-content__inner, +body:has(.openshell-home-page) .md-content__inner { + margin: 0; + padding-top: 0; +} + +body:has(.dev-notes-page) .md-path, +body:has(.openshell-home-page) .md-path { + display: none; +} + +body:has(.dev-notes-page) .md-footer, +body:has(.openshell-home-page) .md-footer { + display: none; +} + +.dev-notes-page, +.dev-notes-page *, +.openshell-home-page, +.openshell-home-page * { box-sizing: border-box; } -.openshell-brand-lockup { +.dev-notes-page { + width: min(calc(100% - 3rem), 60rem); + margin: 0 auto; +} + +.research-masthead { + min-height: min(30rem, calc(100vh - 3.7rem)); + padding: clamp(3.5rem, 9vw, 7.5rem) 0 clamp(3.2rem, 7vw, 5.8rem); + border-bottom: 1px solid var(--openshell-rule-strong); +} + +.research-masthead__topline { + margin-bottom: clamp(2.5rem, 6vw, 5rem); + color: var(--openshell-muted); + font-family: var(--openshell-mono); + font-size: 0.63rem; + letter-spacing: 0.09em; + text-transform: uppercase; +} + +.research-masthead__identity { display: inline-flex; align-items: center; - max-width: 100%; - gap: 0.7rem; - color: var(--openshell-brand-color, var(--openshell-ink)); + gap: 0.65rem; +} + +.research-masthead__identity img { + width: 1.6rem; + height: 1.6rem; +} + +.research-masthead__layout { + display: block; +} + +.research-masthead__copy h1 { + max-width: 13ch; + margin: 0; + font-family: var(--openshell-serif); + font-size: clamp(3.2rem, 7.4vw, 6.25rem); + font-weight: 500; + letter-spacing: -0.06em; + line-height: 0.91; } -.openshell-brand-lockup img { - width: clamp(2.35rem, 5vw, 3.6rem); - height: auto; +.research-masthead__dek { + max-width: 39rem; + margin: 1.8rem 0 0; + color: var(--openshell-muted); + font-family: var(--openshell-serif); + font-size: clamp(1.02rem, 1.9vw, 1.32rem); + line-height: 1.45; +} + +.journal-section { + padding: clamp(3.5rem, 7vw, 6rem) 0 0; +} + +.journal-section__head { + display: flex; + align-items: baseline; + justify-content: space-between; + gap: 1.5rem; + margin-bottom: 1.2rem; + padding-bottom: 0.72rem; + border-bottom: 1px solid var(--openshell-rule-strong); +} + +.md-typeset .journal-section__head h2 { flex: 0 0 auto; + margin: 0; + font-family: var(--openshell-serif); + font-size: clamp(1.45rem, 2.8vw, 2rem); + font-weight: 500; + letter-spacing: -0.035em; + white-space: nowrap; } -.openshell-brand-lockup span { - min-width: 0; - color: inherit; - font-size: clamp(1.45rem, 4.4vw, 2.4rem); - font-weight: 400; - line-height: 1.05; - overflow-wrap: anywhere; +.journal-section__head span { + color: var(--openshell-muted); + font-family: var(--openshell-mono); + font-size: 0.58rem; + letter-spacing: 0.08em; + text-transform: uppercase; } -.openshell-brand-lockup strong { - font-weight: 800; +/* Generated note index ---------------------------------------------------- */ + +.dev-note-card { + margin: 0; } -.openshell-home-hero__brand { - --openshell-brand-color: var(--openshell-home-brand-color); - margin-bottom: 1rem; +.md-typeset .dev-note-card__link { + color: inherit; + text-decoration: none; } -.openshell-home-hero p:last-child { - max-width: 39rem; - margin-bottom: 0; +.md-typeset .dev-note-card__link:hover { + color: inherit; + text-decoration: none; +} + +.dev-note-card--featured .dev-note-card__link { + display: grid; + grid-template-columns: minmax(0, 1.15fr) minmax(19rem, 0.85fr); + min-height: 25rem; + border-bottom: 1px solid var(--openshell-rule); } -.dev-notes-hero { +.dev-note-card__visual { position: relative; - border: 1px solid rgba(255, 255, 255, 0.08); + display: block; + min-height: 100%; + border: 1px solid color-mix(in srgb, var(--openshell-ink) 25%, transparent); background: - linear-gradient(140deg, rgba(118, 185, 0, 0.22), transparent 38%), - linear-gradient(135deg, var(--openshell-ink), var(--openshell-ink-soft) 58%, #17310f); - color: #fff; + radial-gradient(circle at 68% 44%, rgba(118, 185, 0, 0.18) 0 0.34rem, transparent 0.38rem), + linear-gradient(rgba(255, 255, 255, 0.09) 1px, transparent 1px), + linear-gradient(90deg, rgba(255, 255, 255, 0.09) 1px, transparent 1px), + #182326; + background-size: auto, 2.25rem 2.25rem, 2.25rem 2.25rem, auto; + color: #e9ede3; + isolation: isolate; overflow: hidden; } -.dev-notes-hero__brand { - position: relative; - z-index: 1; - --openshell-brand-color: #fff; - margin: clamp(1.15rem, 4vw, 2.1rem) 0 0 clamp(1.25rem, 4vw, 2.5rem); +.dev-note-card__visual::before { + position: absolute; + top: 50%; + left: 50%; + width: min(19rem, 58%); + aspect-ratio: 1; + border: 1px solid var(--openshell-diagram); + border-radius: 50%; + box-shadow: + 0 0 0 2.8rem rgba(120, 145, 142, 0.055), + 0 0 0 5.6rem rgba(120, 145, 142, 0.028); + content: ""; + transform: translate(-50%, -50%); + transition: box-shadow 400ms ease, transform 400ms ease; } -.dev-notes-hero__brand img { - width: clamp(2rem, 4vw, 3rem); +.dev-note-card__visual::after { + position: absolute; + top: 50%; + left: 50%; + width: 72%; + height: 1px; + background: var(--openshell-diagram-bright); + box-shadow: 0 -4.5rem 0 rgba(145, 170, 167, 0.28), 0 4.5rem 0 rgba(145, 170, 167, 0.28); + content: ""; + transform: translate(-50%, -50%) rotate(-31deg); + transform-origin: center; + transition: transform 400ms ease; } -.dev-notes-hero__brand span { - font-size: clamp(1.35rem, 3.4vw, 2rem); +.dev-note-card__visual--runtime, +.dev-note-card__visual--launch { + background: + radial-gradient(circle at 73% 29%, rgba(118, 185, 0, 0.32), transparent 0.6rem), + repeating-radial-gradient(circle at 68% 52%, transparent 0 1.9rem, rgba(255, 255, 255, 0.075) 1.95rem 2rem), + linear-gradient(135deg, #151e20, #2b383b); } -.dev-notes-hero__body { - position: relative; - z-index: 1; - width: 100%; - max-width: clamp(24rem, 58vw, 58rem); - padding: clamp(1rem, 3vw, 1.8rem) clamp(1.25rem, 4vw, 2.5rem) clamp(1.25rem, 4vw, 2.5rem); +.dev-note-card__visual--runtime::before, +.dev-note-card__visual--launch::before { + width: min(16rem, 52%); + border-radius: 0; + transform: translate(-50%, -50%) rotate(45deg); } -.openshell-kicker, -.dev-notes-kicker, -.dev-note-card__meta, -.dev-note-card__tags { +.dev-note-card__visual-label, +.dev-note-card__visual-index, +.dev-note-card__visual-mark { + position: absolute; + z-index: 2; + font-family: var(--openshell-mono); + font-size: 0.58rem; + letter-spacing: 0.08em; + text-transform: uppercase; +} + +.dev-note-card__visual-label { + top: 1rem; + left: 1rem; +} + +.dev-note-card__visual-index { + top: 1rem; + right: 1rem; + color: rgba(233, 237, 227, 0.62); +} + +.dev-note-card__visual-mark { + right: 1rem; + bottom: 0.8rem; + color: var(--openshell-green-soft); + font-size: 1rem; + letter-spacing: -0.1em; +} + +.dev-note-card--featured .dev-note-card__copy { + display: flex; + flex-direction: column; + justify-content: center; + padding: clamp(2rem, 5vw, 4.5rem); + border-top: 1px solid var(--openshell-rule); + border-right: 1px solid var(--openshell-rule); +} + +.dev-note-card__meta { + display: flex; + flex-wrap: wrap; + gap: 0.4rem 0.85rem; margin: 0; - font-size: 0.68rem; - font-weight: 700; - letter-spacing: 0; + color: var(--openshell-muted); + font-family: var(--openshell-mono); + font-size: 0.59rem; + letter-spacing: 0.07em; + line-height: 1.35; text-transform: uppercase; } -.dev-notes-hero h2 { - margin: 0.25rem 0 0.65rem; - color: inherit; - font-size: clamp(1.55rem, 4vw, 2.35rem); - line-height: 1.05; - overflow-wrap: break-word; +.dev-note-card__meta > * + *::before { + margin-right: 0.85rem; + color: var(--openshell-accent-soft); + content: "/"; } -.dev-notes-hero h2 span { - display: inline; +.md-typeset .dev-note-card h3 { + margin: 1.05rem 0 0.8rem; + font-family: var(--openshell-serif); + font-weight: 500; + letter-spacing: -0.04em; } -.dev-notes-hero p:last-child { - margin-bottom: 0; - max-width: 40rem; +.md-typeset .dev-note-card--featured h3 { + font-size: clamp(2rem, 4vw, 3.25rem); + line-height: 1; } -.dev-note-byline__authors { +.dev-note-card__summary { + margin: 0; + color: var(--openshell-muted); + font-family: var(--openshell-serif); + font-size: 0.92rem; + line-height: 1.55; +} + +.dev-note-card__tags { display: flex; flex-wrap: wrap; - gap: 1rem 2rem; + gap: 0.28rem 0.7rem; + margin-top: 0.9rem; + color: var(--openshell-accent); + font-family: var(--openshell-mono); + font-size: 0.54rem; + letter-spacing: 0.045em; + line-height: 1.4; + text-transform: uppercase; +} + +.dev-note-card__tags span::before { + margin-right: 0.12rem; + content: "#"; } -.dev-note-byline__author { +.dev-note-card__footer { + display: flex; + align-items: center; + justify-content: space-between; + gap: 1rem; + margin-top: 2rem; + padding-top: 0.9rem; + border-top: 1px solid var(--openshell-rule); +} + +.dev-note-card__authors { display: inline-flex; align-items: center; - gap: 0.8rem; - color: inherit; - text-decoration: none; + min-width: 0; } -.dev-note-byline__author img { - width: 3.2rem; - height: 3.2rem; +.dev-note-card__authors img { + width: 1.7rem; + height: 1.7rem; flex: 0 0 auto; + border: 2px solid var(--openshell-paper-raised); border-radius: 50%; object-fit: cover; - background: color-mix(in srgb, var(--md-default-fg-color) 10%, transparent); + background: var(--openshell-paper-deep); } -.dev-note-byline__copy { +.dev-note-card__authors img + img { + margin-left: -0.48rem; +} + +.dev-note-card__author-names { + margin-left: 0.65rem; + overflow: hidden; + color: var(--openshell-muted); + font-size: 0.63rem; + text-overflow: ellipsis; + white-space: nowrap; +} + +.dev-note-card__read { + flex: 0 0 auto; + color: var(--openshell-ink); + font-family: var(--openshell-mono); + font-size: 0.59rem; + letter-spacing: 0.06em; + text-transform: uppercase; +} + +.dev-note-card__read::after { + display: inline-block; + margin-left: 0.55rem; + color: var(--openshell-green); + content: "↗"; + transition: transform 180ms ease; +} + +.dev-note-card__link:hover .dev-note-card__visual::before { + box-shadow: + 0 0 0 3.3rem rgba(145, 170, 167, 0.07), + 0 0 0 6.6rem rgba(145, 170, 167, 0.035); + transform: translate(-50%, -50%) scale(1.06); +} + +.dev-note-card__link:hover .dev-note-card__visual::after { + transform: translate(-50%, -50%) rotate(-27deg); +} + +.dev-note-card__link:hover .dev-note-card__read::after { + transform: translate(0.15rem, -0.15rem); +} + +.dev-notes-recent-list { + border-bottom: 1px solid var(--openshell-rule-strong); +} + +.dev-note-card--recent .dev-note-card__link { display: grid; - gap: 0.12rem; + grid-template-columns: minmax(14rem, 0.8fr) minmax(0, 1.2fr); + min-height: 13rem; + padding: 1.2rem 0; + border-top: 1px solid var(--openshell-rule); } -.dev-note-byline__author strong { - color: var(--md-default-fg-color); - font-size: 1rem; - line-height: 1.15; +.dev-note-card--recent:first-child .dev-note-card__link { + border-top: 0; } -.dev-note-byline__copy span { - color: color-mix(in srgb, var(--md-default-fg-color) 70%, transparent); +.dev-note-card--recent .dev-note-card__visual { + min-height: 11rem; +} + +.dev-note-card--recent .dev-note-card__visual::before { + width: 7rem; +} + +.dev-note-card--recent .dev-note-card__visual-index { + top: auto; + right: auto; + bottom: 0.9rem; + left: 1rem; } -.dev-notes-grid { +.dev-note-card--recent .dev-note-card__copy { display: grid; - grid-template-columns: repeat(auto-fit, minmax(min(100%, 17rem), 1fr)); - gap: 0.9rem; - margin: 1rem 0 2rem; + grid-template-columns: minmax(0, 1fr) minmax(11rem, 0.72fr); + grid-template-areas: + "meta meta" + "title summary" + "tags summary" + "footer footer"; + gap: 0.5rem clamp(2rem, 5vw, 4rem); + align-content: center; + padding: 0.75rem 0 0.75rem clamp(1.5rem, 4vw, 3.5rem); } -.dev-note-card { - min-height: 13.5rem; - border: 1px solid color-mix(in srgb, var(--md-default-fg-color) 14%, transparent); - border-radius: 8px; - background: var(--openshell-card-bg); - box-shadow: var(--openshell-card-shadow); - overflow: hidden; +.dev-note-card--recent .dev-note-card__meta { + grid-area: meta; } -.dev-note-card--launch { - border-top: 0.35rem solid var(--openshell-green); +.md-typeset .dev-note-card--recent h3 { + grid-area: title; + margin: 0.65rem 0 0; + font-size: clamp(1.32rem, 2.6vw, 2rem); + line-height: 1.08; } -.md-typeset .dev-note-card__link { +.dev-note-card--recent .dev-note-card__summary { + grid-area: summary; + align-self: start; + margin-top: 0.72rem; + font-size: 0.78rem; +} + +.dev-note-card--recent .dev-note-card__tags { + grid-area: tags; + margin-top: 0.25rem; +} + +.dev-note-card--recent .dev-note-card__footer { + grid-area: footer; + margin-top: 1rem; +} + +.dev-notes-empty { + padding: 3rem 0; + border-bottom: 1px solid var(--openshell-rule-strong); + color: var(--openshell-muted); + font-family: var(--openshell-serif); + font-size: 1.1rem; +} + +.journal-colophon { display: flex; - min-height: inherit; - flex-direction: column; - gap: 0.8rem; - padding: 1.1rem; + align-items: center; + justify-content: space-between; + gap: 2rem; + margin-top: clamp(4rem, 8vw, 7rem); + padding: 1.1rem 0; + border-top: 1px solid var(--openshell-rule-strong); + color: var(--openshell-muted); + font-family: var(--openshell-mono); + font-size: 0.58rem; + letter-spacing: 0.07em; + text-transform: uppercase; +} + +.journal-colophon p { + margin: 0; +} + +.journal-colophon span { + color: var(--openshell-green); +} + +/* Home -------------------------------------------------------------------- */ + +.openshell-home-page { + width: min(calc(100% - 3rem), 60rem); + margin: 0 auto; + padding: clamp(4rem, 10vw, 8rem) 0 clamp(4rem, 8vw, 7rem); +} + +.openshell-home-hero { + display: block; + padding-bottom: clamp(2.75rem, 6vw, 4.5rem); +} + +.openshell-home-hero h1 { + display: flex; + align-items: center; + gap: clamp(1rem, 2vw, 1.75rem); + max-width: none; + margin: 0; + font-family: var(--openshell-serif); + font-size: clamp(3.2rem, 7vw, 5.8rem); + font-weight: 500; + letter-spacing: -0.06em; + line-height: 0.92; +} + +.openshell-home-hero h1 img { + width: 0.88em; + height: 0.88em; + flex: 0 0 auto; +} + +.openshell-home-links { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + border-top: 1px solid var(--openshell-rule-strong); + border-bottom: 1px solid var(--openshell-rule-strong); +} + +.md-typeset .openshell-home-link { + display: flex; + align-items: center; + justify-content: space-between; + gap: 2rem; + min-height: 11rem; + padding: 1.75rem 2rem 1.75rem 0; color: inherit; text-decoration: none; } -.md-typeset .dev-note-card__link:hover { - text-decoration: none; +.md-typeset .openshell-home-link:nth-child(even) { + padding-left: 2rem; + border-left: 1px solid var(--openshell-rule); } -.md-typeset .dev-note-card__link:hover h2 { +.openshell-home-link::after { + flex: 0 0 auto; color: var(--openshell-green); + font-size: 1.3rem; + content: "↗"; } -.dev-note-card h2 { - margin: 0; - font-size: 1.15rem; - line-height: 1.18; +.openshell-home-link__copy { + display: grid; + gap: 0.65rem; } -.dev-note-card p { - margin: 0; - color: color-mix(in srgb, var(--md-default-fg-color) 76%, transparent); +.openshell-home-link__copy strong { + color: var(--openshell-ink); + font-family: var(--openshell-serif); + font-size: 1.65rem; + font-weight: 500; + letter-spacing: -0.02em; } -.dev-note-card__authors { +.openshell-home-link__copy span { + max-width: 25rem; + color: var(--openshell-muted); + font-family: var(--openshell-sans); + font-size: 0.78rem; + line-height: 1.55; +} + +/* Article bylines --------------------------------------------------------- */ + +.dev-note-byline { + margin: -0.5rem 0 2rem; + padding: 1rem 0; + border-top: 1px solid var(--openshell-rule-strong); + border-bottom: 1px solid var(--openshell-rule); +} + +.dev-note-byline__label { + display: flex; + flex-wrap: wrap; + gap: 0.35rem 0.8rem; + margin: 0 0 0.75rem; + color: var(--openshell-muted); + font-family: var(--openshell-mono); + font-size: 0.58rem; + letter-spacing: 0.09em; + text-transform: uppercase; +} + +.dev-note-byline__label > * + *::before { + margin-right: 0.8rem; + color: var(--openshell-accent-soft); + content: "/"; +} + +.dev-note-byline__authors { + display: flex; + flex-wrap: wrap; + gap: 1rem 2.2rem; +} + +.md-typeset .dev-note-byline__author { display: inline-flex; align-items: center; - min-height: 1.75rem; + gap: 0.75rem; + color: inherit; + text-decoration: none; } -.dev-note-card__authors img { - width: 1.55rem; - height: 1.55rem; - border: 2px solid var(--md-default-bg-color); +.dev-note-byline__author img { + width: 2.8rem; + height: 2.8rem; border-radius: 50%; object-fit: cover; + background: var(--openshell-paper-deep); } -.dev-note-card__authors img + img { - margin-left: -0.45rem; +.dev-note-byline__copy { + display: grid; + gap: 0.05rem; } -.dev-note-card__tags { - margin-top: auto; - color: color-mix(in srgb, var(--md-typeset-a-color) 76%, var(--md-default-fg-color)); +.dev-note-byline__author strong { + color: var(--openshell-ink); + font-size: 0.74rem; } -.dev-note-byline { - margin: -0.4rem 0 1.4rem; - padding-bottom: 1rem; - border-bottom: 1px solid color-mix(in srgb, var(--md-default-fg-color) 12%, transparent); +.dev-note-byline__copy span { + color: var(--openshell-muted); + font-size: 0.66rem; } -.dev-note-byline__label { - margin: 0 0 0.65rem; - color: color-mix(in srgb, var(--md-default-fg-color) 58%, transparent); - font-size: 0.64rem; - font-weight: 700; - text-transform: uppercase; +/* Responsive -------------------------------------------------------------- */ + +@media (max-width: 52rem) { + .research-masthead { + min-height: auto; + } + + .dev-note-card--featured .dev-note-card__link { + grid-template-columns: 1fr; + } + + .dev-note-card--featured .dev-note-card__visual { + min-height: 20rem; + } + + .dev-note-card--featured .dev-note-card__copy { + border-left: 1px solid var(--openshell-rule); + } + + .dev-note-card--recent .dev-note-card__copy { + grid-template-columns: 1fr; + grid-template-areas: "meta" "title" "summary" "tags" "footer"; + gap: 0.35rem; + } + } -@media (max-width: 76.25em) { - .dev-notes-hero h2 span { - display: block; +@media (max-width: 44rem) { + .research-masthead__topline { + margin-bottom: 2.6rem; + } + + .research-masthead__identity { + white-space: nowrap; } - .dev-notes-hero h2 { - font-size: 1.42rem; - line-height: 1.12; + .dev-note-card--recent .dev-note-card__link { + grid-template-columns: 1fr; + } + + .dev-note-card--recent .dev-note-card__visual { + min-height: clamp(12rem, 48vw, 17rem); + } + + .dev-note-card--recent .dev-note-card__copy { + padding: 1.3rem 0 0.7rem; } } -@media (max-width: 36rem) { - .md-typeset .openshell-home-hero, - .md-typeset .dev-notes-hero, - .md-typeset .dev-notes-grid { - width: calc(100vw - 2rem); - max-width: calc(100vw - 2rem); +@media (max-width: 38rem) { + .dev-notes-page, + .openshell-home-page { + width: calc(100% - 2rem); + } + + .research-masthead { + padding-top: 2.5rem; + } + + .research-masthead__copy h1 { + font-size: clamp(3rem, 16vw, 4.25rem); + } + + .openshell-home-hero h1 { + gap: 0.75rem; + font-size: clamp(1.6rem, 7.3vw, 3.25rem); + white-space: nowrap; } - .dev-notes-grid { - grid-template-columns: minmax(0, 1fr); + .journal-section__head { + align-items: flex-end; } - .dev-note-card { - min-width: 0; + .journal-section__head span { + max-width: 8rem; + text-align: right; } - .openshell-home-hero, - .dev-notes-hero__body, - .dev-note-card__link { - padding: 1rem; + .dev-note-card--featured .dev-note-card__visual { + min-height: 16rem; } - .dev-notes-hero__body { - max-width: 100%; + .dev-note-card--featured .dev-note-card__copy { + padding: 1.6rem 1.25rem 1.8rem; } - .dev-notes-hero__brand { - margin: 1rem 0 0 1rem; + .dev-note-card--recent .dev-note-card__visual { + min-height: 11.5rem; } - .dev-notes-hero p { - overflow-wrap: break-word; + .dev-note-card--recent .dev-note-card__copy { + padding: 1.2rem 0 0.6rem; } - .dev-notes-hero__brand span { - font-size: clamp(1.2rem, 8vw, 1.55rem); + .dev-note-card__footer { + align-items: center; + flex-wrap: wrap; + } + + .dev-note-card__author-names { + overflow: visible; + line-height: 1.3; + text-overflow: clip; + white-space: normal; + } + + .openshell-home-links { + grid-template-columns: 1fr; + } + + .md-typeset .openshell-home-link:nth-child(even) { + padding-left: 0; + border-left: 0; + border-top: 1px solid var(--openshell-rule); + } + + .journal-colophon { + align-items: flex-start; + flex-direction: column; + gap: 0.35rem; + } +} + +@media (max-width: 24rem) { + .journal-section__head { + gap: 0.75rem; + } + + .journal-section__head span { + max-width: 6.5rem; + font-size: 0.53rem; + line-height: 1.35; + } + + .dev-note-card--featured .dev-note-card__visual-index { + top: auto; + right: auto; + bottom: 0.9rem; + left: 1rem; + } + + .dev-note-card--recent .dev-note-card__footer { + align-items: flex-start; + flex-direction: column; + gap: 0.75rem; + } +} + +@media (prefers-reduced-motion: reduce) { + html { + scroll-behavior: auto; } } diff --git a/scripts/render-dev-notes.py b/scripts/render-dev-notes.py index b5769b21..4f9cdb66 100644 --- a/scripts/render-dev-notes.py +++ b/scripts/render-dev-notes.py @@ -27,6 +27,7 @@ BYLINE_END = "" NAV_START = " # dev-notes:nav:start" NAV_END = " # dev-notes:nav:end" +CANONICAL_DATE = re.compile(r"[0-9]{4}-[0-9]{2}-[0-9]{2}") def parse_scalar(value: str) -> str: @@ -149,16 +150,21 @@ def author_label(authors: list[dict[str, str]]) -> str: return f"{prefix}: {natural_join(names)}" -def format_date(value: str, path: Path) -> str: +def parse_date(value: str, path: Path) -> dt.date: + if not CANONICAL_DATE.fullmatch(value): + raise ValueError(f"{path} date {value!r} must use YYYY-MM-DD") try: - parsed = dt.date.fromisoformat(value) + return dt.date.fromisoformat(value) except ValueError as exc: raise ValueError(f"{path} has invalid ISO date {value!r}") from exc - return f"{parsed.strftime('%B')} {parsed.day}, {parsed.year}" -def post_sort_key(post: dict[str, Any]) -> tuple[str, str]: - return (str(post["metadata"].get("date", "")), str(post["metadata"].get("title", ""))) +def format_date(value: dt.date) -> str: + return f"{value.strftime('%B')} {value.day}, {value.year}" + + +def post_sort_key(post: dict[str, Any]) -> tuple[dt.date, str]: + return (post["published"], str(post["metadata"].get("title", ""))) def discover_posts(authors: dict[str, dict[str, str]]) -> list[dict[str, Any]]: @@ -167,6 +173,7 @@ def discover_posts(authors: dict[str, dict[str, str]]) -> list[dict[str, Any]]: markdown = path.read_text(encoding="utf-8") metadata, raw_frontmatter, body = parse_frontmatter(markdown, path) post_authors = require_authors(require_list(metadata, "authors", path), authors, path) + published = parse_date(require_string(metadata, "date", path), path) posts.append( { "path": path, @@ -174,60 +181,131 @@ def discover_posts(authors: dict[str, dict[str, str]]) -> list[dict[str, Any]]: "frontmatter": raw_frontmatter, "body": body, "authors": post_authors, + "published": published, } ) return sorted(posts, key=post_sort_key, reverse=True) -def render_card(post: dict[str, Any]) -> str: - path = post["path"] +def card_visual_class(post: dict[str, Any]) -> str: + """Choose a stable visual treatment from authored metadata.""" metadata = post["metadata"] - title = require_string(metadata, "title", path) - date = require_string(metadata, "date", path) - description = require_string(metadata, "description", path) - categories = require_list(metadata, "categories", path) - tags = require_list(metadata, "card_tags", path) or require_list(metadata, "tags", path) - authors = post["authors"] - - classes = ["dev-note-card"] variant = str(metadata.get("card_variant", "")).strip() - if variant: - if not re.fullmatch(r"[a-z0-9_-]+", variant): - raise ValueError(f"{path} has invalid card_variant {variant!r}") - classes.append(f"dev-note-card--{variant}") + if variant and not re.fullmatch(r"[a-z0-9_-]+", variant): + raise ValueError(f"{post['path']} has invalid card_variant {variant!r}") + categories = require_list(metadata, "categories", post["path"]) + source = variant or (categories[0] if categories else "research") + slug = re.sub(r"[^a-z0-9_-]+", "-", source.lower()).strip("-") + return slug or "research" + + +def render_card_visual(post: dict[str, Any]) -> str: + metadata = post["metadata"] + categories = require_list(metadata, "categories", post["path"]) + label = categories[0] if categories else "Research" + date_stamp = post["published"].strftime("%Y.%m.%d") + return f""" """ - relative_url = path.relative_to(DEV_NOTES_DIR).with_suffix("").as_posix() + "/" - meta_parts = [format_date(date, path), "Dev Note"] - if categories: - meta_parts.append(categories[0]) +def render_card_authors(authors: list[dict[str, str]]) -> str: author_images = "\n".join( - f' ' + f' ' for author in authors ) - - return f""" """ + {html.escape(names)} + """ + + +def render_card_copy(post: dict[str, Any]) -> str: + path = post["path"] + metadata = post["metadata"] + title = require_string(metadata, "title", path) + published = post["published"] + description = require_string(metadata, "description", path) + categories = require_list(metadata, "categories", path) + tags = require_list(metadata, "card_tags", path) or require_list(metadata, "tags", path) + authors = post["authors"] + category = categories[0] if categories else "Research" + tags_html = "" + if tags: + tag_items = "\n".join(f" {html.escape(tag)}" for tag in tags) + tags_html = f""" +
+{tag_items} +
""" + return f"""
+
+ + {html.escape(category)} +
+

{html.escape(title)}

+

{html.escape(description)}

{tags_html} +
+{render_card_authors(authors)} + Read note +
+
""" + + +def render_featured_card(post: dict[str, Any]) -> str: + relative_url = post["path"].relative_to(DEV_NOTES_DIR).with_suffix("").as_posix() + "/" + variant = card_visual_class(post) + return f""" """ + + +def render_recent_card(post: dict[str, Any]) -> str: + relative_url = post["path"].relative_to(DEV_NOTES_DIR).with_suffix("").as_posix() + "/" + variant = card_visual_class(post) + return f""" """ def render_index_cards(posts: list[dict[str, Any]]) -> str: if not posts: - body = '

No Dev Notes yet.

' + body = '

The first field note is being prepared.

' else: - body = "\n".join(render_card(post) for post in posts) + featured = render_featured_card(posts[0]) + recent_posts = posts[1:] + recent = "\n".join(render_recent_card(post) for post in recent_posts) + recent_section = "" + if recent: + recent_section = f""" +
+
+

Recent notes

+ The working archive +
+
+{recent} +
+
""" + body = f"""
+
+ + Latest from the team +
+{featured} +
{recent_section}""" return ( f"{POSTS_START}\n" "\n" - f'
\n{body}\n
\n' + f"{body}\n" f"{POSTS_END}" ) @@ -236,7 +314,7 @@ def replace_between_markers(content: str, start: str, end: str, replacement: str pattern = re.compile(re.escape(start) + r".*?" + re.escape(end), re.DOTALL) if not pattern.search(content): raise ValueError(f"{path} is missing generated section markers {start!r} and {end!r}") - return pattern.sub(replacement, content, count=1) + return pattern.sub(lambda _: replacement, content, count=1) def update_index(posts: list[dict[str, Any]]) -> None: @@ -279,7 +357,10 @@ def update_nav(posts: list[dict[str, Any]]) -> None: def render_byline(post: dict[str, Any]) -> str: authors = post["authors"] - label = "Author" if len(authors) == 1 else "Authors" + metadata = post["metadata"] + published = post["published"] + categories = require_list(metadata, "categories", post["path"]) + category = categories[0] if categories else "Research" blocks = [] for author in authors: description = author.get("description", "") @@ -295,9 +376,13 @@ def render_byline(post: dict[str, Any]) -> str: return f"""{BYLINE_START} -
-

{label}

-
+
+

+ Field note + + {html.escape(category)} +

+
{chr(10).join(blocks)}
@@ -311,7 +396,7 @@ def update_post_byline(post: dict[str, Any]) -> None: marker_pattern = re.compile(re.escape(BYLINE_START) + r".*?" + re.escape(BYLINE_END), re.DOTALL) if marker_pattern.search(body): - updated_body = marker_pattern.sub(byline, body, count=1) + updated_body = marker_pattern.sub(lambda _: byline, body, count=1) else: heading = re.search(r"(?m)^# .+\n", body) if not heading: diff --git a/tests/test_render_dev_notes.py b/tests/test_render_dev_notes.py new file mode 100644 index 00000000..9e1b0807 --- /dev/null +++ b/tests/test_render_dev_notes.py @@ -0,0 +1,184 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +from __future__ import annotations + +import datetime as dt +import importlib.util +import tempfile +import unittest +from pathlib import Path +from unittest import mock + + +ROOT = Path(__file__).resolve().parents[1] +SCRIPT_PATH = ROOT / "scripts" / "render-dev-notes.py" +SPEC = importlib.util.spec_from_file_location("render_dev_notes", SCRIPT_PATH) +assert SPEC and SPEC.loader +renderer = importlib.util.module_from_spec(SPEC) +SPEC.loader.exec_module(renderer) + + +def make_post( + filename: str, + *, + date: str = "2026-06-05", + title: str = "A field note", + description: str = "What the experiment taught us.", + categories: list[str] | None = None, + tags: list[str] | None = None, + card_tags: list[str] | None = None, + variant: str = "", +) -> dict[str, object]: + path = renderer.POSTS_DIR / filename + metadata: dict[str, object] = { + "title": title, + "date": date, + "description": description, + "categories": categories or ["Systems"], + "tags": tags or ["agents", "runtime"], + } + if card_tags is not None: + metadata["card_tags"] = card_tags + if variant: + metadata["card_variant"] = variant + return { + "path": path, + "metadata": metadata, + "frontmatter": "", + "body": f"# {title}\n", + "authors": [{"name": "Ada Lovelace", "github": "ada"}], + "published": renderer.parse_date(date, path), + } + + +class DateValidationTests(unittest.TestCase): + def test_accepts_only_canonical_calendar_dates(self) -> None: + path = Path("post.md") + self.assertEqual(renderer.parse_date("2026-01-02", path), dt.date(2026, 1, 2)) + + for value in ("20260102", "2026-1-02", "２０２６-０１-０２", "2026-02-30"): + with self.subTest(value=value), self.assertRaises(ValueError): + renderer.parse_date(value, path) + + def test_discovery_sorts_by_parsed_date_then_title(self) -> None: + authors = {"ada": {"name": "Ada Lovelace", "github": "ada"}} + with tempfile.TemporaryDirectory() as directory: + posts_dir = Path(directory) + for filename, title, date in ( + ("older.md", "Older", "2025-12-31"), + ("zeta.md", "Zeta", "2026-01-01"), + ("alpha.md", "Alpha", "2026-01-01"), + ): + (posts_dir / filename).write_text( + "\n".join( + ( + "---", + f"title: {title}", + f"date: {date}", + "description: Test post.", + "authors:", + " - ada", + "---", + f"# {title}", + "", + ) + ), + encoding="utf-8", + ) + + with mock.patch.object(renderer, "POSTS_DIR", posts_dir): + posts = renderer.discover_posts(authors) + + self.assertEqual([post["metadata"]["title"] for post in posts], ["Zeta", "Alpha", "Older"]) + + +class CardRenderingTests(unittest.TestCase): + def test_zero_one_and_many_post_layouts(self) -> None: + first = make_post("2026-06-05-first.md") + second = make_post("2026-06-04-second.md", date="2026-06-04", title="Second") + third = make_post("2026-06-03-third.md", date="2026-06-03", title="Third") + + self.assertIn("first field note", renderer.render_index_cards([])) + one = renderer.render_index_cards([first]) + self.assertIn("Featured note", one) + self.assertNotIn("Recent notes", one) + many = renderer.render_index_cards([first, second, third]) + self.assertEqual(many.count("dev-note-card--recent"), 2) + + def test_visual_stamp_uses_stable_canonical_date(self) -> None: + post = make_post("2026-06-05-note.md") + visual = renderer.render_card_visual(post) + self.assertIn("2026.06.05", visual) + self.assertNotIn("OSR—", visual) + + def test_card_tags_override_tags_and_variant_reaches_outer_card(self) -> None: + post = make_post( + "2026-06-05-note.md", + tags=["fallback"], + card_tags=["preferred", "evaluation"], + variant="launch", + ) + card = renderer.render_featured_card(post) + self.assertIn("dev-note-card--launch", card) + self.assertIn(">preferred<", card) + self.assertIn(">evaluation<", card) + self.assertNotIn(">fallback<", card) + + def test_metadata_is_html_escaped(self) -> None: + post = make_post( + "2026-06-05-note.md", + title="Runtime