Restructuring website navigation and content

README.md

@@ -1,4 +1,176 @@
 <div align="center">
+  <img src="./logo.svg" alt="Armada logo" width="200"/>
+
+  <h3>One API. Any number of clusters. Millions of jobs.</h3>
+  <p>The open-source batch job meta-scheduler that makes Kubernetes work at scale.</p>
+
+  <p>
+    <a href="https://circleci.com/gh/armadaproject/armada"><img src="https://circleci.com/gh/armadaproject/armada.svg?style=shield" alt="CircleCI"></a>
+    <a href="https://goreportcard.com/report/github.com/armadaproject/armada"><img src="https://goreportcard.com/badge/github.com/armadaproject/armada" alt="Go Report Card"></a>
+    <a href="https://artifacthub.io/packages/helm/gresearch/armada" title="Go to Artifact Hub"><img src="https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/armada" alt="Artifact Hub"></a>
+    <a href="https://insights.linuxfoundation.org/project/armada" title="Click to view project insights and health checks"><img src="https://insights.linuxfoundation.org/api/badge/health-score?project=armada" alt="LFX Health Score"></a>
+    <a href="https://www.bestpractices.dev/projects/11485"><img src="https://www.bestpractices.dev/projects/11485/badge" alt="OpenSSF Best Practices"></a>
+  </p>
+
+  <p>
+    <a href="https://armadaproject.io">Website</a> ·
+    <a href="https://armadaproject.io/quickstart">Quickstart</a> ·
+    <a href="https://armadaproject.io/docs">Documentation</a> ·
+    <a href="https://cloud-native.slack.com/archives/C03T9CBCEMC">Slack</a>
+  </p>
+</div>
+
+---
+
+## What is Armada?
+
+Kubernetes was built for services. Armada was built for batch.
+
+When your job volume exceeds what a single cluster can handle, you need a control plane that sits above your fleet — routing jobs intelligently, fairly, and at scale. Armada is that layer.
+
+**Armada solves the problems Kubernetes wasn't designed to handle:**
+
+- **No job queue** — Kubernetes has no concept of ordering. Jobs compete for resources with no fairness guarantees. Armada adds a proper queue with priority, fair-share, and rate limiting.
+- **No multi-cluster coordination** — Each Kubernetes cluster is an island. Armada routes jobs across as many clusters as you need from a single API.
+- **No gang scheduling** — Distributed jobs that need all workers to start simultaneously (MPI, PyTorch, Spark) have no atomic startup guarantee in vanilla Kubernetes. Armada either starts the whole group or holds it.
+- **No fairness across teams** — One team can starve everyone else. Armada enforces fair-share scheduling so heavy users don't permanently dominate shared infrastructure.
+
+Armada is used in production at [G-Research](https://www.gresearch.co.uk/) since 2020, processing **millions of batch jobs per day** across tens of thousands of nodes.
+
+---
+
+## Features
+
+| Feature | Description |
+|---|---|
+| 🌐 **Multi-cluster scheduling** | One API across unlimited Kubernetes clusters |
+| ⚖️ **Fair-share queuing** | Dominant resource fairness across teams and queues |
+| 🔗 **Gang scheduling** | Atomic startup for distributed workloads |
+| ⚡ **Preemption** | Urgent jobs bump lower-priority work automatically |
+| 📊 **Prometheus metrics** | Full observability into queue health and cluster utilisation |
+| 🔭 **Lookout UI** | Web interface for monitoring jobs, queues, and clusters |
+| 🔒 **Enterprise-ready** | Secure, highly available, OIDC authentication support |
+
+---
+
+## Getting started
+
+The fastest way to get Armada running locally is with the [Armada Operator](https://github.com/armadaproject/armada-operator):
+
+```bash
+git clone https://github.com/armadaproject/armada-operator.git
+cd armada-operator
+make kind-all
+```
+
+→ **[Full quickstart guide](https://armadaproject.io/quickstart)** — get up and running in under 15 minutes.
+
+### armadactl
+
+Armada's CLI for interacting with the system:
+
+```bash
+# download via script
+scripts/get-armadactl.sh
+
+# or grab the binary from the releases page
+https://github.com/armadaproject/armada/releases/latest
+```
+
+---
+
+## Local development
+
+Armada runs locally via [Goreman](https://github.com/mattn/goreman) — dependencies (Redis, Postgres, Pulsar) run in containers, Armada components run as host processes built from source. Iteration is fast and debuggers attach directly.
+
+```bash
+mage kind                  # one-time: create local Kubernetes cluster
+export KUBECONFIG=.kube/external/config
+
+mage dev:up                # default — no auth
+mage dev:up auth           # with OIDC via Keycloak
+mage dev:up fake-executor  # no Kubernetes cluster needed
+mage dev:down              # stop dependency containers
+```
+
+→ **[Full local development guide](https://armadaproject.io/docs/developer-guide)** — profiles, procfiles, service ports, authentication, and debugging.
+
+---
+
+## Use cases
+
+Armada is used wherever batch jobs are too large, too many, or too complex for a single Kubernetes cluster:
+
+- **Quantitative finance & HPC** — millions of short-lived simulations per day with fair-share across research teams
+- **ML and AI training** — distributed GPU training with gang scheduling across clusters  
+- **Platform engineering** — multi-tenant batch infrastructure with a single API surface
+- **SLURM migration** — familiar scheduling semantics (queues, priorities, preemption) on Kubernetes-native infrastructure
+- **CI/CD at scale** — priority control so critical merges always run first
+
+---
+
+## In production
+
+Armada has been running in production at [G-Research](https://www.gresearch.co.uk/) since 2020.
+
+**Running Armada in production?** Open a PR to add yourself to [ADOPTERS.md](./ADOPTERS.md) 🙌
+
+---
+
+## Community
+
+Everyone is welcome — come and say hi! 👋
+
+- 💬 **Slack** — [#armada on CNCF Slack](https://cloud-native.slack.com/archives/C03T9CBCEMC) — fastest way to get help and talk to maintainers
+- 💡 **GitHub Discussions** — [longer-form questions and ideas](https://github.com/armadaproject/armada/discussions)
+- 🐛 **GitHub Issues** — [bug reports and feature requests](https://github.com/armadaproject/armada/issues)
+- 📅 **Community meetings** — bi-weekly, open to all. Join [#armada on Slack](https://cloud-native.slack.com/archives/C03T9CBCEMC) for the invite link
+- ⭐ **Star the repo** — helps more people find Armada
+
+---
+
+## Contributing
+
+We'd love your contributions — code, docs, bug reports, or ideas. All are welcome.
+
+- Read [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines
+- Check [good first issues](https://github.com/armadaproject/armada/labels/good%20first%20issue) for a starting point
+- All commits require a [DCO sign-off](https://developercertificate.org/): `git commit -s`
+- Please review [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) before contributing
+
+---
+
+## Documentation
+
+| Resource | Link |
+|---|---|
+| Website & overview | [armadaproject.io](https://armadaproject.io) |
+| Quickstart | [armadaproject.io/quickstart](https://armadaproject.io/quickstart) |
+| Architecture | [armadaproject.io/docs/architecture](https://armadaproject.io/docs/architecture) |
+| API reference | [armadaproject.io/docs/api](https://armadaproject.io/docs/api) |
+| Developer guide | [armadaproject.io/docs/developer-guide](https://armadaproject.io/docs/developer-guide) |
+| Release notes | [github.com/armadaproject/armada/releases](https://github.com/armadaproject/armada/releases) |
+
+---
+
+## Talks and videos
+
+- [Armada — high-throughput batch scheduling](https://www.youtube.com/watch?v=FT8pXYciD9A)
+- [Building Armada — Running Batch Jobs at Massive Scale on Kubernetes](https://www.youtube.com/watch?v=B3WPxw3OUl4)
+
+---
+
+<div align="center">
+  <br/>
+  <img src="https://raw.githubusercontent.com/cncf/artwork/master/other/cncf/horizontal/color/cncf-color.png" width="180" alt="CNCF logo"/>
+  <br/>
+  <sub>Armada is a <a href="https://www.cncf.io/">Cloud Native Computing Foundation</a> Sandbox project 🚀</sub>
+  <br/>
+  <sub>Apache 2.0 License</sub>
+</div>
+
+
+<!-- <div align="center">
  <img src="./logo.svg" alt="Armada logo" width="200"/>
  <p>
   <a href="https://circleci.com/gh/armadaproject/armada"><img src="https://circleci.com/gh/armadaproject/armada.svg?style=shield" alt="CircleCI"></a>
@@ -107,4 +279,4 @@ For more information about contributing to Armada see [CONTRIBUTING.md](https://
 
 ## Discussion
 
-If you are interested in discussing Armada you can find us on [![slack](https://img.shields.io/badge/slack-armada-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/?redir=%2Farchives%2FC03T9CBCEMC)
+If you are interested in discussing Armada you can find us on [![slack](https://img.shields.io/badge/slack-armada-brightgreen.svg?logo=slack)](https://cloud-native.slack.com/?redir=%2Farchives%2FC03T9CBCEMC) -->

website/.remarkignore

@@ -9,3 +9,6 @@ tmp.*
 # Auto-generated files
 python-airflow-operator.md
 python-armada-client.md
+
+# Archived files
+_archive/

website/.remarkrc-md.mjs

@@ -2,7 +2,19 @@ const remarkConfig = {
   plugins: [
     'remark-preset-lint-consistent',
     'remark-frontmatter',
-    'remark-validate-links',
+    [
+      'remark-validate-links',
+      {
+        // Internal links use absolute Next.js routes (e.g. /docs/clients),
+        // not file paths. remark-validate-links resolves paths from the git
+        // root and has no extension resolution, so it can't check these.
+        // Skip route-shaped links; relative links and heading anchors are
+        // still validated.
+        // TODO: add a post-build link check against the static export to
+        // properly validate routes (see check-links.sh).
+        skipPathPatterns: [/\/[^/.]+\/?(#[^/]*)?$/],
+      },
+    ],
     [
       'remark-lint-no-dead-urls',
       {

website/.remarkrc-mdx.mjs

@@ -2,7 +2,19 @@ const remarkConfig = {
   plugins: [
     'remark-mdx',
     'remark-mdx-frontmatter',
-    'remark-validate-links',
+    [
+      'remark-validate-links',
+      {
+        // Internal links use absolute Next.js routes (e.g. /docs/clients),
+        // not file paths. remark-validate-links resolves paths from the git
+        // root and has no extension resolution, so it can't check these.
+        // Skip route-shaped links; relative links and heading anchors are
+        // still validated.
+        // TODO: add a post-build link check against the static export to
+        // properly validate routes (see check-links.sh).
+        skipPathPatterns: [/\/[^/.]+\/?(#[^/]*)?$/],
+      },
+    ],
     [
       'remark-lint-no-dead-urls',
       {

website/README.md

@@ -1,42 +1,118 @@
-# Armada - documentation website
+# Armada Website Readme
 
-This is a [Next.js](https://nextjs.org) project, based on the [Fumadocs](https://fumadocs.dev) framework, bootstrapped
-using:
-
-- [`npx create-next-app@latest`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
-- [`yarn create fumadocs-app`](https://github.com/fuma-nama/fumadocs).
+The Armada documentation site is built with [Next.js](https://nextjs.org) and [Fumadocs](https://fumadocs.dev). All content is written in MDX, Markdown that can include React components.
 
 ## Requirements
 
-- Node.js >= 20.x
-- Yarn ~1.22.22
+Before you start, make sure you have the following installed:
+
+- **Node.js** >= 20.x — [Download](https://nodejs.org)
+- **Yarn** ~1.22.22 — install with `npm install -g yarn` if you don't have it
+
+## Getting started
 
-## Installation
+All commands should be run from inside the `website/` folder. If you are at the root of the `armada` repository, navigate there first:
 
-```shell
+```bash
+cd website
+```
+
+### Install dependencies
+
+```bash
 yarn install
 ```
 
-## Local Development
+### Start the local dev server
 
 ```bash
 yarn dev
 ```
 
-Open http://localhost:3000 on your browser to see the result.
+Open [http://localhost:3000](http://localhost:3000) in your browser. The page will hot-reload as you edit files — you do not need to restart the server after making changes to content or components.
 
-## Build and Preview
+### GitHub Pages base path
 
-To build the project for production and preview it, run:
+The live site is deployed to GitHub Pages under a base path. If your changes involve links, images, or assets and you want to make sure they resolve correctly in that environment, copy `.env.example` to `.env.local` and set the base path before running the preview:
 
 ```bash
-yarn build
-# then
-yarn preview
+cp .env.example .env.local
+```
+
+Then open `.env.local` and follow the instructions inside. You do not need this for most content changes: only if you are working on routing, assets, or the Next.js config itself.
+
+## How the site works
+
+Every page on the site is an `.mdx` file under `content/`. MDX is Markdown that can also use React components. You write normal Markdown and drop in components (cards, callouts, custom JSX) where you need them.
+
+### Content structure
+
+content/
+├── index.mdx # Homepage / landing page
+├── getting-started.mdx # Quickstart guide
+├── meta.json # Root nav configuration
+├── docs/ # All documentation pages
+│ ├── meta.json
+│ ├── core-concepts.mdx
+│ ├── developer-guide.mdx
+│ └── ...
+└── contribute/ # Contributing section
+├── meta.json
+└── ...
+
+### How the left sidebar nav works
+
+The left sidebar is driven entirely by `meta.json` files — Fumadocs reads them at build time and constructs the page tree from them.
+
+**Root nav — `content/meta.json`**
+
+**Section nav — `content/docs/meta.json`**
+
+A `meta.json` inside a folder controls that section's title, page order, and which pages appear.
+
+**To add a page to the nav:**
+
+1. Create the `.mdx` file in the right folder
+2. Add the filename (without `.mdx`) to the relevant `meta.json` pages array
+
+**To remove a page from the nav:**
+Remove it from `meta.json`.
+
+**To reorder pages:**
+Change the order in the `meta.json` pages array. Top to bottom = top to bottom in the sidebar.
+
+**Important:** A folder with no `meta.json` is completely invisible to the nav. The pages exist and are routable URLs but won't appear in the sidebar. If a page you created isn't showing up, check whether its folder has a `meta.json` and whether that file is listed in it.
+
+### Right TOC
+
+Generated automatically from `##` and `###` Markdown headings only. JSX elements and styled `<div>`/`<span>` tags do not appear in the TOC regardless of how they look visually.
+
+### The homepage
+
+The homepage is `content/index.mdx` — a content page like any other, served by the `[[...slug]]` catch-all route. The `_(home)` route group in `src/app/` handles the root `/` path and renders `index.mdx` directly.
+
+### The `not-prose` rule
+
+Fumadocs applies typography styles to all MDX content by default. Any custom JSX layout block — a hero section, a card grid, a CTA — needs the `not-prose` class on its outermost element, otherwise Fumadocs' prose styles will override your custom styles:
+
+```mdx
+<div className='not-prose flex flex-col items-center'>
+  {/* your custom layout here */}
+</div>
 ```
 
-The preview server will start on http://localhost:3000 by default. It also supports base path configuration to mimic
-the GitHub Pages environment. Check the `.env.example` file to see how to set it up.
+### Markdown links inside JSX
+
+Markdown link syntax (`[text](url)`) does not render inside JSX elements. Use anchor tags instead:
+
+```mdx
+{/* This won't work inside a JSX div */}
+[CNCF](https://cncf.io)
+
+{/* Use this instead */}
+
+<a href='https://cncf.io'>CNCF</a>
+```
 
 ## Format, Lint Content, Lint Code and Spell Check
 

website/content/operator-guide.mdx → website/_archive/operator-guide.mdx

@@ -26,7 +26,7 @@ Armada consists of several components that work together:
 - **Lookout**: Provides job monitoring and web UI
 - **Supporting services**: Pulsar (message broker), PostgreSQL, and Redis
 
-For a detailed explanation of how these components interact, see the [Architecture documentation](./understanding-armada/architecture.mdx).
+For a detailed explanation of how these components interact, see the [Architecture documentation](docs/architecture.mdx).
 
 ## Local Installation
 
@@ -449,11 +449,11 @@ If you encounter issues not covered here:
 
 - **GitHub Issues**: Report bugs and request features at [github.com/armadaproject/armada/issues](https://github.com/armadaproject/armada/issues)
 - **Community Slack**: Join discussions on [CNCF Slack](https://cloud-native.slack.com/?redir=%2Farchives%2FC03T9CBCEMC)
-- **Documentation**: Check the [Architecture documentation](./understanding-armada/architecture.mdx) for system design details
+- **Documentation**: Check the [Architecture documentation](docs/architecture.mdx) for system design details
 
 ## Additional Resources
 
-- [Architecture Overview](./understanding-armada/architecture.mdx) - Understand how Armada components work
+- [Architecture Overview](docs/architecture.mdx) - Understand how Armada components work
 - [User Guide](./user-guide) - Learn how to submit and manage jobs
 - [Armada Operator](https://github.com/armadaproject/armada-operator) - Kubernetes-native deployment option
 - [Helm Charts Documentation](https://github.com/armadaproject/armada/tree/master/deployment) - Detailed Helm configuration reference