Repository navigation
Docs: infrastructure and structure for documentation overhaul - #1452
Conversation
Create external-links.adoc with all external URLs as Antora attributes (akka.io product pages, blog posts, customer stories, demos, webinars, foundational resources, community links). Include it in the global partials chain so every page can reference external links via attributes. When a URL changes, update it in one place — every page picks it up. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New top-level entry point framing the three barriers (Production Gap, Liability, Specialist Trap) and three dimensions (Reliability, Risk Control, Repeatability). Includes competitive comparison table and links to external content via the link registry. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Brief platform intro covering full-stack positioning, key differentiators, service tiers (Fast Prod through Sovereign Cloud), and application types with links to akka.io product pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Lists every user persona (Builders, Operators, Governance & Oversight) with curated links to the docs they care about. Includes customer stories organized by industry vertical. Serves as a routing page for both humans and AI agents. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Browsable collection of all non-docs content organized by type: foundational works (Reactive Manifesto, Reactive Principles), product pages, application types, blogs, demos, talks, webinars, customer stories, benchmarks, training, and community links. All URLs use the external link registry. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New Understanding page explaining why bolt-on governance fails for agentic AI (immutable records, human intervention, authorization capture, PII scrubbing) and how Akka embeds governance in the runtime. Covers EU AI Act alignment and compliance certifications. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Update antora.yml nav order: ROOT (Why/What/Who) -> Tutorials -> Understanding -> Developing -> Operating -> Resources -> Reference - ROOT nav.adoc now includes Why Akka, What is Akka, Who Uses Akka - New resources-nav.adoc for the Resources top-level section - Rewrite homepage: lead with positioning (three barriers/dimensions), SDD-first tutorial ordering, Governance & Runtime in Understanding, AAO leading Operating, Resources section added Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
CLAUDE.md provides context for any Claude session working on this codebase: positioning, documentation principles, platform details, PR strategy, build commands, and repo structure. docs/docs-overhaul-spec.md is the full specification for the documentation restructuring project including writing standards, page audit, use case mappings, integration details, llms.txt spec, and implementation requirements. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
Hi @TylerJewell, Thank you for your contribution! We really value the time you've taken to put this together. Before we proceed with reviewing this pull request, please sign the Akka Contributors License Agreement: |
Add: Anthropic, biopharma, decisioning, Doctolib, explainability, Hanafee, infosec, Llaama, Manulife, QCon, regionalized, reputational, Swiggy, Telecom, Tubi to the Vale spelling accept list. These are proper nouns, industry terms, and customer names used in new documentation pages. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
791660d to
36dec4c
Compare
ennru
left a comment
There was a problem hiding this comment.
I agree, this adds necessary background that wasn't covered before.
The spec should not be added, I think. But we can merge and remove it later.
| 3. Editing individual `nav.adoc` files for section-level changes | ||
|
|
||
| ### External Link Registry | ||
| All external URLs defined as Antora attributes in a **single central file**: `docs/src/modules/ROOT/partials/external-links.adoc` (new file). Included by every page via the existing `include::ROOT:partial$include.adoc[]` chain. |
There was a problem hiding this comment.
This only makes it harder for humans to look at content sources. No gain AFAICS.
| Follows the **llms.txt specification** created by Jeremy Howard (fast.ai/Answer.AI, Sep 2024). Both files are **fully auto-generated** every time the Antora docs are built. No hand-maintained files. The existing `docs/src/modules/ROOT/pages/llms.txt` (currently hand-maintained) is replaced by generated output. The build pipeline (`docs-prod.yml`) handles rsyncing to `doc.akka.io`. | ||
|
|
||
| **Standard file names and purposes:** | ||
|
|
||
| - **`/llms.txt`** — A curated **index** in Markdown format. Contains a project summary, organized H2 sections of links (`- [Title](url): description`), and an `## Optional` section for supplementary content that can be dropped when context is tight. An agent reads this to understand what docs are available, then selectively fetches only the pages it needs. Small file (1-5 KB). |
There was a problem hiding this comment.
"No hand-maintained" and "curated" is a contradiction, isn't it?
| [discrete] | ||
| == xref:ROOT:why-akka.adoc[Why Akka] | ||
|
|
||
| Three barriers stand between AI prototypes and production: the **Production Gap**, **Liability**, and the **Specialist Trap**. xref:ROOT:why-akka.adoc[Learn how Akka solves them]. |
There was a problem hiding this comment.
I can imagine better formatting as a list.
| Akka is the agentic systems platform built for Reliability, Risk Control, and Repeatability at enterprise scale. The only full-stack platform for agentic AI: developer experience, runtime, and governance in one integrated system. | ||
|
|
||
| [discrete] | ||
| == xref:ROOT:why-akka.adoc[Why Akka] |
There was a problem hiding this comment.
Title links are generally hard to discover by the reader. But we have those already.
| @@ -0,0 +1,57 @@ | |||
| = Governance & the runtime | |||
Summary
external-links.adocpartial with all external URLs as Antora attributes. One file to update when URLs change.docs/docs-overhaul-spec.mdcovering positioning, writing standards, platform details, page audit, and implementation requirements.Each change is an individually reviewable commit.
Test plan
make localor Docker-based Antora build succeeds with no new errors🤖 Generated with Claude Code