Click the Castor logo or press Ctrl Alt T to change theme.
# Generated site behavior Castor Docs generates static HTML, a static `search-index.json`, and a small `castor-packages.mjs` browser module. The PHP generator does not parse Markdown into HTML; the browser does the dynamic work. The generated site starts in the visitor's system color scheme unless they have chosen a theme before. Readers can switch between light and dark mode by clicking the Castor logo in the sidebar or by pressing <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>T</kbd>. The choice is stored as `castor-theme` in `localStorage`, so every documentation site served from `castor-labs.github.io` can start with the same theme. ## Client-side Markdown Each page embeds its Markdown source as escaped JSON in an `application/json` script tag. In the browser: 1. `marked` converts Markdown to HTML. 2. `DOMPurify` sanitizes the generated HTML before insertion. 3. `highlight.js` highlights fenced code blocks. 4. A tiny Castor Docs script decorates headings, callouts, code language badges, the theme toggle, and search results. 5. `castor-packages.mjs` loads the public Castor Composer repository when the reader opens the package explorer. This keeps generation simple while still producing a fully static site. ## Search Generation writes a `search-index.json` file next to the generated pages. The index contains each page title, output URL, plain text extracted from the Markdown, and a short excerpt. The search box loads that JSON file in the browser and performs a simple case-insensitive substring search across page titles and page text. Results are rendered as links to the matching generated pages. Markdown links to local Markdown pages are rewritten during generation. For example, `[Configuration](configuration.html)` becomes a link to the generated `configuration.html`, and anchors are preserved. Search is intentionally local and static: - no server endpoint; - no indexing service; - no build-time database; - no third-party search account. Press `/` to focus the search box. ## Syntax highlighting Use fenced Markdown code blocks with a language name: ````md ```php <?php echo 'Hello Castor'; ``` ```` The generated page shows the language badge in the top-right corner of the block and highlights the code with `highlight.js`. The stylesheet switches between light and dark Highlight.js themes when the user changes the page theme. ## Callouts GitHub-style callouts are supported: ```md > [!TIP] > Keep `.dev/docs-dist` ignored and let CI generate it. ``` Supported types are `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, and `DANGER`. Each callout receives a matching icon, border color, title color, and background color. ## Tables and blockquotes Tables use a minimal reference style with no side borders, a strong header separator, and subtle row separators. Blockquotes use the display font, italic text, and a slim left border, matching the Castor visual language. ## Layout and scroll behavior On desktop, the sidebar, content, and on-page table of contents are fixed to the viewport height. The main content column scrolls internally and the footer remains sticky at the bottom of that column. Previous and next pages are also available as edge navigation bars, so readers do not need to scroll to the bottom to move through the guide. The sidebar includes an **Explore other packages…** button near the package identity. It opens a fixed-size, scrollable dialog that loads the current Castor package list directly from the public Composer registry. Because this happens in the browser, a package added to the registry appears in existing documentation sites without rebuilding them. Packages are grouped as dependencies, dependants, other packages, and abandoned packages. The dialog has enough room to show each package name, description, status, and destination link. Readers can open it with the button or with <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>K</kbd>, which works well on desktop while the same dialog remains comfortable on mobile. Scrollbars are themed for both Firefox and WebKit browsers. On smaller screens, the layout falls back to normal document scrolling. ## Version badge detection The version badge is derived from package metadata in this order: 1. If the configured `composer.json` contains a `version` field, that value is used. 2. Otherwise, Castor Docs asks Git whether `HEAD` is exactly on a tag with `git describe --tags --exact-match HEAD`. 3. If no exact tag exists and the current branch is `main` or `master`, the badge shows `latest`. 4. Otherwise, the badge falls back to `dev`. Semantic versions are displayed as a minor series instead of an exact patch release. For example, `v1.2.3` and `1.2.3` both display as `1.2.x`. This means release builds generated from tagged commits automatically show the release series, default branch builds show `latest`, and unreleased feature branch builds clearly show `dev`. ## Footer Every page includes a sticky footer. Configure it in `.dev/docs/config.php`: ```php $docs->footer('© 2026 Castor Labs Ltd - All rights reserved'); ``` If no footer is configured, Castor Docs uses: ```text © <current_year> Castor Labs Ltd - All rights reserved ```
Castor ecosystem