Skip to content

RHCLOUD-47186: Deprecate the internal docs overlay #109

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tonytheleg merged 2 commits into from
Jun 11, 2026
Merged

RHCLOUD-47186: Deprecate the internal docs overlay #109

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3388dc5
updates contributing guide and claude/agent files for the new interna…
tonytheleg Jun 10, 2026
efa430f
removes config.overlay.js
tonytheleg Jun 10, 2026
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
12 changes: 7 additions & 5 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,13 +141,15 @@ This system has three cooperating parts:

When editing client-package pages, the API surface is defined entirely in YAML frontmatter, not in the Markdown body. The specification uses JavaScript conventions (`camelCase`) as canonical; implementations transform to language-specific conventions.

## Fork and Overlay Architecture
## Internal Documentation

This repository is designed to be forked for internal documentation. The `config-overlay.mjs` file provides two hook functions:
- `applyTopLevelOverlay(config)` -- modifies top-level Astro config (site URL, base path, integrations)
- `applyStarlightOverlay(starlightConfig)` -- modifies Starlight config (sidebar entries, plugins)
This repository contains the public Kessel documentation. Supplemental internal documentation -- covering Red Hat-specific onboarding, hosted environment configuration, operational runbooks, and monitoring -- is maintained in a separate repository and published to InScope (Red Hat's internal developer portal, accessible via VPN).

**Critical rule**: In the public repository, changes to `config-overlay.mjs` and `astro.config.mjs` must be made carefully as they affect internal forks. The warning in `config-overlay.mjs` is explicit: modifications may break internal mirroring. In a fork, you MUST NOT modify files that originate from the public repository.
Content belongs in the right place:
- **Public docs (this repo)**: Integration guides, SDK docs, API reference, concepts, and anything relevant to all Kessel users.
- **Internal docs (InScope)**: Red Hat-specific configuration, credentials setup, ephemeral testing, hosted architecture, runbooks, and monitoring procedures.

Do not add Red Hat-specific operational content to this repository.

## Cross-Cutting Conventions

Expand Down
9 changes: 4 additions & 5 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,10 @@ This repository uses `rh-multi-pre-commit` for Red Hat security scanning. The ho

## Claude Code Behavioral Preferences

### File modification priority
- **CRITICAL**: This repository has a fork/overlay architecture for internal documentation
- Modifications to `config-overlay.mjs` and `astro.config.mjs` affect internal forks - exercise extreme caution
- The warning in `config-overlay.mjs` is explicit: modifications may break internal mirroring
- When making changes to these files, follow up immediately to resolve conflicts in forks
### Content placement
- This repository is for **public** Kessel documentation only
- Internal Red Hat-specific content (onboarding, hosted config, runbooks, monitoring) belongs in the separate internal docs repo published to InScope
- Do not add Red Hat-specific operational content to this repository

### Content creation
- Use `.mdx` for pages needing Astro components (`Aside`, `Tabs`, `CodeExamples`, etc.)
Expand Down
7 changes: 4 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ src/
docs/ # AI agent guidelines
public/ # Static assets (favicon)
astro.config.mjs # Astro and Starlight configuration
config-overlay.mjs # Fork/overlay hooks for internal documentation
```

Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
Expand All @@ -44,6 +43,8 @@ See [Writing documentation](src/content/docs/contributing/documentation.mdx).

## Internal documentation

This repository can be forked to augment with internal deployment documentation. [config-overlay.mjs](config-overlay.mjs) is designed to be overridden by forks in order to modify the sidebar for the inclusion of e.g. internal documentation.
This repository contains the public Kessel documentation. Supplemental internal documentation covering Red Hat-specific onboarding, hosted environment configuration, operational runbooks, and monitoring, is maintained separately and published to InScope (Red Hat's internal developer portal, accessible via VPN). The internal docs expand on the public content with details that cannot be published externally.

Keep this in mind when making changes to this repository–note which repository you are working in. Inside the fork, you MUST not modify files which come from the public docs repository. In the public docs repository, care must be taken when modifying explicitly shared and overriden files, like `config-overlay.mjs`.
When contributing, keep content in the right place:
- **Public docs (this repo)**: Integration guides, SDK docs, API reference, concepts, and anything relevant to all Kessel users.
- **Internal docs (InScope)**: Red Hat-specific configuration, credentials setup, ephemeral testing, hosted architecture, runbooks, and monitoring procedures.
36 changes: 0 additions & 36 deletions config-overlay.mjs
View file
Open in desktop

This file was deleted.

Loading