From 71597c076f2d7cdf09f5d4e010f94a3a6e37f297 Mon Sep 17 00:00:00 2001 From: Shmuel Osovski Date: Thu, 10 Sep 2026 14:03:05 +0300 Subject: [PATCH 1/2] docs: render the material icons instead of printing their names MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The homepage cards are written with Material's icon shorthand (`:material-graph:`, `:material-memory:` and so on), but `pymdownx.emoji` was never enabled, so nothing resolved them and the published site showed the literal text. Enabling it with Material's twemoji index and SVG generator is the documented requirement for `.icons` shorthand. Verified against a strict build: `:material-` appears zero times in the built index.html, and four inline SVG icons render in the card grid. Four, not five — the compmech-reference-pack card lost its icon and title line when the package was dropped from the public tree, leaving an orphaned body. That is a separate fix. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01TcdE6eeSDBh8xrgKCoGrkw --- mkdocs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index a2e4523..0d1980e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -63,6 +63,12 @@ markdown_extensions: - pymdownx.inlinehilite - pymdownx.snippets - pymdownx.smartsymbols + # Resolves `:material-graph:` and friends into inline SVG. Without this the + # docs render the literal text `:material-graph:` — which is what the + # published homepage cards were doing. + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - pymdownx.keys - pymdownx.tabbed: alternate_style: true From d90611bc2e40614a2d1dab4b75ed30dd1a549620 Mon Sep 17 00:00:00 2001 From: Shmuel Osovski Date: Thu, 10 Sep 2026 14:58:17 +0300 Subject: [PATCH 2/2] docs: adopt the house theme, repair the companion-adapter card, set the site URL MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three corrections to the published documentation surface. **The house theme.** Ports the look from dev/demos/02-adaptive-path.html onto Material as docs/stylesheets/akms.css: the light and dark palettes, the 16/20px radii, the 2.5px card borders and the hard offset shadows. The demo scopes its tokens to [data-theme]; Material stamps [data-md-color-scheme], so the palettes are re-scoped and mapped onto Material's own --md-* variables rather than restated as a parallel system. `primary`/`accent` move to `custom` so the stylesheet wins — a named Material colour would override it. Typography is deliberately not a literal port. The demo sets a cursive face for body and monospace text, which costs too much on reference tables, API signatures and code blocks. Baloo 2 carries the identity on headings and the header rule; body and code keep Material's readable defaults. **The companion-adapter card.** docs/index.md carried an orphaned card body — a `---` and a description with no icon or title line — left behind when compmech-reference-pack was dropped from the public tree. It rendered as a detached paragraph inside the grid. Restored as a proper card pointing at the architecture page that documents extension points, worded so it describes the adapter without implying it is installable yet. **The site URL.** site_url was an empty string and repo_url/edit_uri were absent, all three marked "finalized at publication time". They are knowable now, and site_url drives canonical links and the sitemap. Verified on a strict build: five cards render inline SVG icons, zero literal `:material-` remains, the stylesheet is linked and emitted, and the canonical link resolves to https://cemm2.github.io/AKMS/index.html. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01TcdE6eeSDBh8xrgKCoGrkw --- docs/index.md | 6 +- docs/stylesheets/akms.css | 200 ++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 20 ++-- 3 files changed, 217 insertions(+), 9 deletions(-) create mode 100644 docs/stylesheets/akms.css diff --git a/docs/index.md b/docs/index.md index f0453d4..b8615c3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -37,11 +37,13 @@ omnivorous agent framework: Batch Picker and generation tools for turning source collections into validated AKMS nodes, including a NotebookLM CLI path. +- :material-function-variant: __[Companion adapters](architecture/modules.md)__ --- - Optional companion adapter that bridges computational-mechanics LSP - excerpts to the MechDSL executable backend while preserving provenance. + Executable-domain bridges such as `compmech-reference-pack`, which maps + computational-mechanics LSP excerpts onto the MechDSL backend while + preserving provenance. diff --git a/docs/stylesheets/akms.css b/docs/stylesheets/akms.css new file mode 100644 index 0000000..e8549f5 --- /dev/null +++ b/docs/stylesheets/akms.css @@ -0,0 +1,200 @@ +/* AKMS documentation theme. + * + * Ports the house look from dev/demos/02-adaptive-path.html onto MkDocs + * Material. The demo scopes its tokens to [data-theme="light"|"dark"]; Material + * stamps [data-md-color-scheme="default"|"slate"], so the palettes are + * re-scoped here and mapped onto Material's own --md-* variables rather than + * being restated as a parallel system. + * + * Typography is deliberately not a literal port. The demo sets a cursive face + * for body and monospace text, which costs too much on reference tables, API + * signatures and code blocks. Baloo 2 carries the identity on headings and the + * header; body and code keep Material's readable defaults. + */ + +@import url("https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&display=swap"); + +:root { + --akms-radius: 16px; + --akms-radius-card: 20px; + --akms-card-border-width: 2.5px; + --akms-red: #e63b2e; + --akms-font-display: "Baloo 2", system-ui, sans-serif; +} + +/* ========== LIGHT ========== */ +[data-md-color-scheme="default"] { + --akms-bg: #fff8e7; + --akms-surface: #ffffff; + --akms-elevated: #fff0cc; + --akms-border: #e8b84b; + --akms-text-muted: #6b5b3e; + --akms-shadow: 3px 4px 0 #2b2b2b; + --akms-shadow-hover: 5px 6px 0 #2b2b2b; + + --md-primary-fg-color: #e63b2e; + --md-primary-fg-color--light: #f06055; + --md-primary-fg-color--dark: #b22e24; + --md-primary-bg-color: #ffffff; + --md-accent-fg-color: #2b78c4; + + --md-default-bg-color: #fff8e7; + --md-default-fg-color: #2b2b2b; + --md-default-fg-color--light: #6b5b3e; + --md-default-fg-color--lighter: #9a8a6e; + --md-typeset-color: #2b2b2b; + --md-typeset-a-color: #2b78c4; + --md-code-bg-color: #fff0cc; + --md-code-fg-color: #2b2b2b; + --md-footer-bg-color: #2b2b2b; +} + +/* ========== DARK ========== */ +[data-md-color-scheme="slate"] { + --akms-bg: #0d1117; + --akms-surface: #161b22; + --akms-elevated: #1c2128; + --akms-border: #484f58; + --akms-text-muted: #8b949e; + --akms-shadow: 3px 4px 0 #000000; + --akms-shadow-hover: 5px 6px 0 #000000; + + --md-primary-fg-color: #161b22; + --md-primary-fg-color--light: #1c2128; + --md-primary-fg-color--dark: #0d1117; + --md-primary-bg-color: #f0f6fc; + --md-accent-fg-color: #58a6ff; + + --md-default-bg-color: #0d1117; + --md-default-fg-color: #c9d1d9; + --md-default-fg-color--light: #8b949e; + --md-default-fg-color--lighter: #6e7681; + --md-typeset-color: #c9d1d9; + --md-typeset-a-color: #58a6ff; + --md-code-bg-color: #161b22; + --md-code-fg-color: #c9d1d9; + --md-footer-bg-color: #161b22; +} + +/* ========== DISPLAY TYPE ========== */ +.md-typeset h1, +.md-typeset h2, +.md-typeset h3, +.md-typeset h4, +.md-header__title, +.md-nav__title { + font-family: var(--akms-font-display); + letter-spacing: 0.01em; +} + +.md-typeset h1, +.md-typeset h2 { + font-weight: 800; +} + +/* The demo's signature: a hard rule under the top bar in the accent red. */ +.md-header { + box-shadow: 0 3px 0 var(--akms-red); +} + +[data-md-color-scheme="default"] .md-header { + box-shadow: 0 3px 0 #b22e24; +} + +/* ========== CARDS ========== */ +.md-typeset .grid.cards > ul > li, +.md-typeset .grid > .card { + background: var(--akms-surface); + border: var(--akms-card-border-width) solid var(--akms-border); + border-radius: var(--akms-radius-card); + box-shadow: var(--akms-shadow); + transition: + transform 0.15s ease, + box-shadow 0.15s ease; +} + +.md-typeset .grid.cards > ul > li:hover, +.md-typeset .grid > .card:hover { + transform: translate(-2px, -2px); + box-shadow: var(--akms-shadow-hover); + border-color: var(--md-accent-fg-color); +} + +/* Card icons pick up the accent rather than sitting in body grey. */ +.md-typeset .grid.cards > ul > li > hr + p > .twemoji, +.md-typeset .grid.cards > ul > li > p > .twemoji { + color: var(--md-accent-fg-color); +} + +.md-typeset .grid.cards > ul > li .twemoji svg { + width: 1.6em; + height: 1.6em; +} + +/* ========== ADMONITIONS, QUOTES, TABLES ========== */ +.md-typeset .admonition, +.md-typeset details { + border-width: var(--akms-card-border-width); + border-radius: var(--akms-radius); + box-shadow: var(--akms-shadow); +} + +.md-typeset blockquote { + border-left: var(--akms-card-border-width) solid var(--akms-border); + border-radius: 0 var(--akms-radius) var(--akms-radius) 0; + background: var(--akms-elevated); + color: var(--akms-text-muted); + padding: 0.4rem 0.8rem; +} + +.md-typeset table:not([class]) { + border: var(--akms-card-border-width) solid var(--akms-border); + border-radius: var(--akms-radius); + overflow: hidden; + box-shadow: var(--akms-shadow); +} + +.md-typeset table:not([class]) th { + background: var(--akms-elevated); + font-family: var(--akms-font-display); + font-weight: 700; +} + +/* ========== CODE ========== */ +.md-typeset pre > code, +.md-typeset .highlight { + border-radius: var(--akms-radius); +} + +.md-typeset .highlight { + border: 1.5px solid var(--akms-border); +} + +.md-typeset code { + border-radius: 6px; +} + +/* ========== BUTTONS AND PILLS ========== */ +.md-typeset .md-button { + border-width: var(--akms-card-border-width); + border-radius: var(--akms-radius); + box-shadow: var(--akms-shadow); + font-family: var(--akms-font-display); + font-weight: 600; +} + +.md-typeset .md-button:hover { + transform: translate(-1px, -1px); + box-shadow: var(--akms-shadow-hover); +} + +/* ========== NARROW SCREENS ========== */ +/* The offset shadows read as clutter once cards go full-bleed. */ +@media screen and (max-width: 44.9375em) { + .md-typeset .grid.cards > ul > li, + .md-typeset table:not([class]), + .md-typeset .admonition, + .md-typeset details { + box-shadow: none; + } +} diff --git a/mkdocs.yml b/mkdocs.yml index 0d1980e..ae7915c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -2,9 +2,10 @@ site_name: AKMS site_description: >- Adaptive Knowledge Management System — deterministic graph, task-context, loadout, learning, and project-memory infrastructure for coding and research agents. -# site_url / repo_url are finalized at publication time. -site_url: "" -# edit_uri is restored with repo_url at publication time. +site_url: "https://cemm2.github.io/AKMS/" +repo_url: "https://github.com/CEmM2/AKMS" +repo_name: CEmM2/AKMS +edit_uri: edit/main/docs/ docs_dir: docs site_dir: site @@ -14,17 +15,19 @@ theme: name: material language: en palette: + # `custom` hands primary/accent to docs/stylesheets/akms.css, which defines + # them per scheme. A named Material colour here would win instead. - media: "(prefers-color-scheme: light)" scheme: default - primary: indigo - accent: indigo + primary: custom + accent: custom toggle: icon: material/weather-night name: Switch to dark mode - media: "(prefers-color-scheme: dark)" scheme: slate - primary: indigo - accent: indigo + primary: custom + accent: custom toggle: icon: material/weather-sunny name: Switch to light mode @@ -82,6 +85,9 @@ markdown_extensions: - pymdownx.arithmatex: generic: true +extra_css: + - stylesheets/akms.css + plugins: - search - mkdocstrings: