From da3202cd057d6182729c9c9b061e10bca5264711 Mon Sep 17 00:00:00 2001 From: Michal Harakal Date: Mon, 13 Apr 2026 20:35:12 +0200 Subject: [PATCH] =?UTF-8?q?Adopt=20skainet-docs-ui=20v1.1.1=20+=20Di=C3=A1?= =?UTF-8?q?taxis=20card-grid=20landing=20(#501)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two coupled changes that swap mainline's Antora UI bundle for the new SKaiNET-branded skainet-docs-ui release and rewrite the landing page to use its card-grid component. ## docs/antora-playbook.yml Pin ui.bundle.url to: https://github.com/SKaiNET-developers/skainet-docs-ui/releases/download/v1.1.1/ui-bundle.zip Replaces the upstream gitlab.com/antora/antora-ui-default URL that mainline had been pinned to since the Antora migration in #494/#495. The new bundle is the shared SKaiNET docs UI from the new skainet-docs-ui repo (https://github.com/SKaiNET-developers/skainet-docs-ui) which ships: - SKaiNET red palette (#dc2626) with light + dark mode - Orbitron (display) + Inter (body) + Fira Code (mono) - Class-based dark mode toggle (FOUC-safe via inline head bootstrap) - 6px thin custom scrollbar - Rounded code blocks with GitHub-light / GitHub-dark - Primary-red focus glow on links / buttons - SKaiNET footer (replaces the upstream MPL-2.0 / antora-ui boilerplate) - .card-grid CSS for landing-page card grids - Mobile responsive (hamburger menu from upstream preserved) Pinned to v1.1.1 specifically (not floating on latest) so mainline builds are reproducible. Bumping the pin is a one-line follow-up PR whenever skainet-docs-ui ships a new minor. ## docs/modules/ROOT/pages/index.adoc Replaces the placeholder "Quick links" section with a real [.card-grid] block that surfaces the four Diátaxis sections (Tutorials / How-to / Reference / Explanation) as clickable cards with one-line descriptions. Each card links to the first real page of its section: Tutorials -> tutorials/java-getting-started.adoc How-to -> how-to/build.adoc Reference -> reference/architecture.adoc (with inline xrefs to operator catalog + ops-status-matrix + Dokka API) Explanation -> explanation/skainet-for-ai.adoc The [.card-grid] role is rendered into a responsive grid by the new CSS in skainet-docs-ui's src/css/skainet-polish.css (landed in v1.1.0). Falls back to a normal bulleted list on any consumer that doesn't ship the SKaiNET CSS — never a broken render. The Diátaxis NOTE admonition pointing at SKaiNET-transformers for LLM runtimes stays — that was added in the original migration to make the repo split visible. ## Verification Local Antora build against the published v1.1.1 bundle URL (no --ui-bundle-url override): docker run --rm --user "$(id -u):$(id -g)" \ -v "$PWD:/antora" -w /antora \ skainet-antora:local docs/antora-playbook.yml - exit 0 - rendered index.html contains
with the four cards - rendered footer contains the SKaiNET-attribution links to skainet-docs-ui, mainline, and SKaiNET-transformers - all other pages (tutorials, how-to, reference, explanation, operator catalog, ops-status-matrix) render unchanged but in the new red-on-dark/light theme Closes #501. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/antora-playbook.yml | 6 ++++- docs/modules/ROOT/pages/index.adoc | 41 ++++++++++++++++++------------ 2 files changed, 30 insertions(+), 17 deletions(-) diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index 5c9493cf..f5b32045 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -30,7 +30,11 @@ asciidoc: ui: bundle: - url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable + # SKaiNET-branded UI bundle from the shared skainet-docs-ui repo: + # https://github.com/SKaiNET-developers/skainet-docs-ui + # Pinned to a specific tag for reproducible builds. Bumping + # this URL to a newer version is a one-line PR. + url: https://github.com/SKaiNET-developers/skainet-docs-ui/releases/download/v1.1.1/ui-bundle.zip snapshot: true output: diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index fd1fda7e..b8ad69f4 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -9,26 +9,35 @@ platform compile targets, and a pluggable backend API that CPU, GPU, and NPU backends can implement independently. This documentation site is organized following the -https://diataxis.fr/[Diátaxis / Divio framework]: +https://diataxis.fr/[Diátaxis / Divio framework] — pick the +section that matches what you're trying to do: -Tutorials:: Learning-oriented. Start here if you are new to SKaiNET. -How-to guides:: Task-oriented. Recipes for solving specific problems. -Reference:: Information-oriented. Looking up APIs and op coverage. -Explanation:: Understanding-oriented. Background on design decisions. +[.card-grid] +* xref:tutorials/java-getting-started.adoc[*Tutorials*] ++ +Learning-oriented walkthroughs. Start here if you are new to +SKaiNET — set up a project, build your first tensor, run a +forward pass. +* xref:how-to/build.adoc[*How-to guides*] ++ +Task-oriented recipes. Build from source, load a GGUF model, +generate C for Arduino, train a small network from Java. +* xref:reference/architecture.adoc[*Reference*] ++ +Information-oriented lookup: architecture, the +xref:reference/operators/generated/index.adoc[operator catalog], +the xref:reference/ops-status-matrix.adoc[backend coverage matrix], +and the link:../api/index.html[Dokka API reference]. +* xref:explanation/skainet-for-ai.adoc[*Explanation*] ++ +Understanding-oriented background: SKaiNET for AI/ML, the +operator documentation system, mathematical theory, performance +notes. [NOTE] ==== LLM-specific runtimes (Llama, Gemma, Qwen, BERT) live in the sibling https://github.com/SKaiNET-developers/SKaiNET-transformers[SKaiNET-transformers] -repository and its own documentation site. This site covers the -engine layer only. +repository and its own documentation site. Mainline SKaiNET +covers the engine layer only. ==== - -== Quick links - -* link:../api/index.html[API reference (Dokka)] (bundled at publish time) - -// The Tutorials / How-to / Reference / Explanation pages plus the -// operator coverage xref land in follow-up commits (#2 and #3 of -// the Antora migration). This page ships the landing copy first so -// the scaffold build succeeds with a real start_page.