Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 3 additions & 5 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This file helps AI coding agents (and humans) understand how to work with this r

This is the **Stackable Documentation** site, built with [Antora](https://antora.org/).
It aggregates AsciiDoc content from this repo plus ~18 operator repos from the `stackabletech` GitHub org.
The UI comes from a git submodule in `ui/` (the [documentation-ui](https://github.com/stackabletech/documentation-ui) repo).
The UI lives in the `ui/` directory and is bundled during the build.

## Prerequisites

Expand All @@ -18,7 +18,6 @@ The UI comes from a git submodule in `ui/` (the [documentation-ui](https://githu
## Setup

```sh
git submodule update --init # fetch the UI submodule
npm ci # install dependencies
```

Expand Down Expand Up @@ -67,7 +66,6 @@ Then open `http://localhost:8000`.
## Quick Start (copy-paste)

```sh
git submodule update --init
npm ci
make ANTORAFLAGS=--fetch build-only-dev
make serve
Expand All @@ -77,7 +75,7 @@ make serve

- `antora.yml` — Defines the `home` Antora component (version, nav, attributes)
- `modules/` — Platform-level documentation content (concepts, guides, tutorials, operators, etc.)
- `ui/` — Git submodule pointing to [documentation-ui](https://github.com/stackabletech/documentation-ui); bundled by gulp
- `ui/` — The site UI (a fork of antora-ui-default, see `ui/UPSTREAM`); bundled by gulp
- `supplemental-ui/` — UI overrides and the `stackable-operator-helpers.js` Antora extension
- `*-playbook.yml` — Antora playbook files (see Build Targets above)
- `cache/` — Antora's git cache directory (gitignored, remove with `make clean`)
Expand Down Expand Up @@ -131,7 +129,7 @@ Cross-repo xrefs will break if any sibling repo is on a different branch or has

### UI bundle not found

Run `git submodule update --init` to fetch the UI submodule, then `npm ci` to install dependencies (including gulp).
Run `npm ci` to install dependencies (including gulp), then `make build-ui`.

## Agent Skills

Expand Down
3 changes: 1 addition & 2 deletions modules/contributor/pages/docs/overview.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,6 @@
:pagefind: https://pagefind.app/
:stackable-docs-readme: https://github.com/stackabletech/documentation/blob/main/README.adoc
:stackable-docs-repo: https://github.com/stackabletech/documentation
:stackable-docs-ui-repo: https://github.com/stackabletech/documentation-ui
:trunk-based-development: https://trunkbaseddevelopment.com/

We use {antora-docs}[Antora{external-link-icon}^] to write our user facing documentation,
Expand Down Expand Up @@ -56,7 +55,7 @@ The xref:docs/style-guide.adoc[] contains all the information about the writing
{antora-docs}[Antora{external-link-icon}^] uses a {antora-playbook}[playbook{external-link-icon}^] to build the documentation.
It pulls documentation content from all the individual operator repositories, so an operators documentation is maintained in the same repository as the code.
Antora builds a static website which we serve over {netlify}[Netlify{external-link-icon}^].
The web template of the documentation is also custom made and is developed in the {stackable-docs-ui-repo}[documentation-ui{external-link-icon}^] repository.
The web template of the documentation is also custom made and lives in the `ui/` directory of the {stackable-docs-repo}[documentation repository{external-link-icon}^].

For search, we use {pagefind}[pagefind{external-link-icon}^] - a static search.
The search index is generated as part of the build process and no external index is queried during search.
Expand Down
Loading