Skip to content

Commit 7a7ef04

Browse files
chris-colinskychris-colinsky
authored
docs(site): UX, nav, and reference cleanup (#53)
* docs(site): UX, nav, and reference cleanup First of the docs-phase PRs. - Expand the spec mention on the homepage into a standalone section linking to openarmature.org (was a paragraph reference only). - Drop `navigation` from the homepage `hide:` list so the left nav renders on the landing page. - Make the "OpenArmature" wordmark clickable via a local override of Material's header partial. The homepage variant also suppresses the default wordmark/page-title scroll swap, which read as a render glitch when both texts are identical. - Add Parallel branches to the Concepts nav (proposal 0011 landed without it). - Refresh the Reference index: add openarmature.prompts; note parallel-branches, multimodal/structured output, and the state-migration registry on existing entries; drop the boilerplate trailer about underscored symbols. * docs(site): apply PR review fixes - Header partial override: enumerate both local modifications in the top comment (was written when only the anchor wrap existed and not updated when the homepage pinning logic was added). Resync-on-bump guidance is the whole point of that comment, so it needs to list everything that must be preserved. - Homepage spec section: capitalize "OpenArmature" to match the page H1 and README convention; reserve the lowercase form for code spans referring to the Python package. Replace the em dash on the same line with a comma.
1 parent 0b10e04 commit 7a7ef04

5 files changed

Lines changed: 155 additions & 14 deletions

File tree

‎docs/index.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
---
22
hide:
3-
- navigation
43
- toc
54
---
65

@@ -65,7 +64,11 @@ buy-in from every node.
6564

6665
---
6766

68-
Built around an open, language-agnostic
69-
[specification](https://github.com/LunarCommand/openarmature-spec){target="_blank" rel="noopener"}.
70-
A TypeScript implementation is on the roadmap; behaviour stays
71-
identical across implementations via spec conformance fixtures.
67+
## Open specification
68+
69+
OpenArmature is defined by a public, language-agnostic specification,
70+
not a Python-shaped opinion exported to other languages. Reference
71+
implementations share conformance fixtures, so behavior stays identical
72+
across languages, runtimes, and tooling stacks.
73+
74+
[Read the spec →](https://openarmature.org){target="_blank" rel="noopener"}

‎docs/overrides/partials/header.html‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
{#-
2+
Local override of material/partials/header.html.
3+
4+
Local modifications vs. the upstream partial:
5+
6+
1. The site-name topic in ``.md-header__title`` is rendered as an
7+
``<a>`` (carrying the ``md-header__topic`` class) so the visible
8+
"OpenArmature" wordmark navigates home. Upstream's default leaves
9+
that topic as a plain ``<div>``; the only header-area link is the
10+
icon-style ``md-logo`` button, which our extra.css hides because
11+
we want the wordmark on its own.
12+
2. On the homepage (``page.is_homepage``), the ``.md-header__title``
13+
element gets an extra ``md-header__title--pinned`` class and the
14+
second ``.md-header__topic`` (the page-title topic) is not
15+
rendered. A paired rule in extra.css pins the wordmark in place
16+
regardless of ``data-md-state="topic"`` so the scroll animation
17+
doesn't fire; we omit the page-title topic because on the
18+
homepage it would just be an un-bold copy of "OpenArmature".
19+
20+
Re-sync this file when bumping mkdocs-material; preserve both
21+
modifications. Everything below is otherwise verbatim from the
22+
upstream partial.
23+
-#}
24+
{% set class = "md-header" %}
25+
{% if "navigation.tabs.sticky" in features %}
26+
{% set class = class ~ " md-header--shadow md-header--lifted" %}
27+
{% elif "navigation.tabs" not in features %}
28+
{% set class = class ~ " md-header--shadow" %}
29+
{% endif %}
30+
<header class="{{ class }}" data-md-component="header">
31+
<nav class="md-header__inner md-grid" aria-label="{{ lang.t('header') }}">
32+
<a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" title="{{ config.site_name | e }}" class="md-header__button md-logo" aria-label="{{ config.site_name }}" data-md-component="logo">
33+
{% include "partials/logo.html" %}
34+
</a>
35+
<label class="md-header__button md-icon" for="__drawer">
36+
{% set icon = config.theme.icon.menu or "material/menu" %}
37+
{% include ".icons/" ~ icon ~ ".svg" %}
38+
</label>
39+
{#- LOCAL OVERRIDE: pin the wordmark on the homepage. The page title
40+
there is also "OpenArmature", so Material's default scroll
41+
animation flips between the bold wordmark and the un-bold page
42+
title of the same text, which reads as a glitch. On the
43+
homepage we tag the title element so extra.css can suppress the
44+
swap, and we skip rendering the page-title topic entirely. -#}
45+
<div class="md-header__title{% if page.is_homepage %} md-header__title--pinned{% endif %}" data-md-component="header-title">
46+
<div class="md-header__ellipsis">
47+
{# LOCAL OVERRIDE: render the site-name topic as an <a> so the
48+
wordmark is clickable. Material's default markup is a plain
49+
<div class="md-header__topic">; we substitute an anchor that
50+
carries the same .md-header__topic class so the theme's
51+
positioning rules (which target direct children of
52+
.md-header__ellipsis) still apply. #}
53+
<a href="{{ config.extra.homepage | d(nav.homepage.url, true) | url }}" class="md-header__topic md-header__topic-link" aria-label="{{ config.site_name }}">
54+
<span class="md-ellipsis">
55+
{{ config.site_name }}
56+
</span>
57+
</a>
58+
{% if not page.is_homepage %}
59+
<div class="md-header__topic" data-md-component="header-topic">
60+
<span class="md-ellipsis">
61+
{% if page.meta and page.meta.title %}
62+
{{ page.meta.title }}
63+
{% else %}
64+
{{ page.title }}
65+
{% endif %}
66+
</span>
67+
</div>
68+
{% endif %}
69+
</div>
70+
</div>
71+
{% if config.theme.palette %}
72+
{% if not config.theme.palette is mapping %}
73+
{% include "partials/palette.html" %}
74+
{% endif %}
75+
{% endif %}
76+
{% if not config.theme.palette is mapping %}
77+
{% include "partials/javascripts/palette.html" %}
78+
{% endif %}
79+
{% if config.extra.alternate %}
80+
{% include "partials/alternate.html" %}
81+
{% endif %}
82+
{% if "material/search" in config.plugins %}
83+
{% set search = config.plugins["material/search"] | attr("config") %}
84+
{% if search.enabled %}
85+
<label class="md-header__button md-icon" for="__search">
86+
{% set icon = config.theme.icon.search or "material/magnify" %}
87+
{% include ".icons/" ~ icon ~ ".svg" %}
88+
</label>
89+
{% include "partials/search.html" %}
90+
{% endif %}
91+
{% endif %}
92+
{% if config.repo_url %}
93+
<div class="md-header__source">
94+
{% include "partials/source.html" %}
95+
</div>
96+
{% endif %}
97+
</nav>
98+
{% if "navigation.tabs.sticky" in features %}
99+
{% if "navigation.tabs" in features %}
100+
{% include "partials/tabs.html" %}
101+
{% endif %}
102+
{% endif %}
103+
</header>

‎docs/reference/index.md‎

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,16 @@
33
Auto-generated from docstrings. Pick a subpackage:
44

55
- [`openarmature.graph`](graph.md): state, builder, edges, nodes,
6-
projections, fan-out, middleware, observer, reducers, errors.
6+
projections, fan-out, parallel branches, middleware, observer,
7+
reducers, errors.
78
- [`openarmature.llm`](llm.md): Provider Protocol, message + tool
8-
types, the OpenAIProvider, shared error helpers.
9+
types, multimodal content blocks, structured output, the
10+
OpenAIProvider, shared error helpers.
11+
- [`openarmature.prompts`](prompts.md): PromptManager, PromptBackend
12+
Protocol, FilesystemPromptBackend, PromptGroup, prompt
13+
observability propagation.
914
- [`openarmature.checkpoint`](checkpoint.md): Checkpointer Protocol,
10-
CheckpointRecord, in-memory + SQLite backends.
15+
CheckpointRecord, in-memory + SQLite backends, state-migration
16+
registry.
1117
- [`openarmature.observability`](observability.md): correlation
1218
primitives and the optional OTel mapping (`[otel]` extra).
13-
14-
Public surface is what each subpackage's `__init__.py` re-exports. Symbols
15-
prefixed with `_` are package-private and not shown here.

‎docs/stylesheets/extra.css‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -157,13 +157,39 @@
157157
color: #cd8bf4;
158158
}
159159

160-
/* Hide the default Material book-icon logo next to the site name; the
161-
* "OpenArmature" wordmark stands on its own and already links to the
162-
* site root. */
160+
/* Hide the default Material book-icon logo next to the site name. The
161+
* "OpenArmature" wordmark itself is made clickable by the local
162+
* ``docs/overrides/partials/header.html`` override, which wraps the
163+
* site-name topic in an ``<a>`` pointing at the site root. */
163164
.md-header__button.md-logo {
164165
display: none;
165166
}
166167

168+
/* Inherit header text colors on the wordmark anchor introduced by the
169+
* partial override, so it reads as the wordmark rather than a styled
170+
* link. */
171+
.md-header__topic-link,
172+
.md-header__topic-link:hover,
173+
.md-header__topic-link:focus,
174+
.md-header__topic-link:visited {
175+
color: inherit;
176+
text-decoration: none;
177+
}
178+
179+
/* Suppress the wordmark/page-title scroll animation on the homepage.
180+
* The homepage's page title is also "OpenArmature", so Material's
181+
* default swap flips between the bold wordmark and the un-bold
182+
* page-title of the same text — reads as a render glitch. The
183+
* ``--pinned`` modifier is added by the partial override when
184+
* ``page.is_homepage`` is true, and we don't render the second topic
185+
* at all in that case; this rule keeps the wordmark visible regardless
186+
* of the ``data-md-state="topic"`` toggle Material adds on scroll. */
187+
.md-header__title--pinned .md-header__topic {
188+
opacity: 1;
189+
pointer-events: auto;
190+
transform: none;
191+
}
192+
167193
/* Hide Material's auto-generated site-name header at the top of the
168194
* primary sidebar — we have an explicit ``OpenArmature: index.md``
169195
* entry in the nav config which serves as the home link. */

‎mkdocs.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,11 @@ dev_addr: "127.0.0.1:8765"
99

1010
theme:
1111
name: material
12+
# Override directory for theme partials. ``docs/overrides/`` carries
13+
# the customized ``partials/header.html`` that makes the
14+
# "OpenArmature" wordmark clickable (Material's default leaves it
15+
# as a plain ``<div>``).
16+
custom_dir: docs/overrides
1217
palette:
1318
- media: "(prefers-color-scheme: light)"
1419
scheme: default
@@ -94,6 +99,7 @@ nav:
9499
- Graphs: concepts/graphs.md
95100
- Composition: concepts/composition.md
96101
- Fan-out: concepts/fan-out.md
102+
- Parallel branches: concepts/parallel-branches.md
97103
- LLMs: concepts/llms.md
98104
- Prompts: concepts/prompts.md
99105
- Observability: concepts/observability.md

0 commit comments

Comments
 (0)