Click the Castor logo or press Ctrl Alt T to change theme.
# Full rendering example This page is a kitchen-sink example for checking the Castor Docs theme. It intentionally uses common Markdown features so package maintainers can preview spacing, typography, code, tables, lists, quotes, and callouts in one place. ## Paragraphs and inline formatting Documentation pages should feel comfortable to read for long stretches. A normal paragraph can include **strong emphasis**, *emphasis*, `inline code`, and links like [the Castor package repository](https://castor-labs.github.io/php-packages/). A second paragraph demonstrates rhythm between blocks. Keep prose concise, but do not be afraid of explaining intent: documentation is often the first maintainer a user meets. ## Lists Unordered lists are useful for short collections: - Zero runtime dependencies for the PHP generator. - Static output that can be deployed anywhere. - Client-side Markdown rendering, sanitization, highlighting, and search. - Opinionated conventions for Castor packages. Ordered lists work well for procedures: 1. Create `.dev/docs/index.md`. 2. Add documentation pages under `.dev/docs/pages`. 3. Configure sections in `.dev/docs/config.php` when needed. 4. Run `vendor/bin/castor-docs generate`. Nested lists are supported by the browser Markdown renderer: - Source files - `index.md` for the site landing page. - `pages/index.md` for the docs landing page. - Generated files - `index.html` - `docs/index.html` - `search-index.json` ## Blockquotes > Documentation is part of the API. If users cannot understand how to use a package, the package is not finished. Blockquotes are best for short notes, quotes, or principles that should stand apart from the main flow. ## Callouts > [!NOTE] > Notes contain neutral information that helps users understand context without interrupting the guide. > [!TIP] > Tips highlight better workflows. For example, keep `.dev/docs-dist` ignored and let CI build it. > [!IMPORTANT] > Important callouts should be used sparingly for details users must not miss. > [!WARNING] > Warnings describe risky choices, compatibility concerns, or destructive behaviour such as replacing the target directory. > [!DANGER] > Danger callouts are reserved for actions that can cause data loss or security issues. Callouts can also contain **emphasised text**, `inline code`, and links. The callout title and strong text inherit the callout colour. ## Code blocks Shell commands render with syntax highlighting when the client-side highlighter supports the language: ```bash composer require --dev castor-labs/docs vendor/bin/castor-docs generate --source=.dev/docs --target=.dev/docs-dist ``` PHP examples use the same code block treatment: ```php <?php use Castor\Docs\Documentation; return static function (Documentation $docs): void { $docs->addComposerJsonPath(__DIR__ . '/../../composer.json'); $docs->section('Guides', [ 'guides/conventions.md', 'guides/configuration.md', 'guides/rendering-example.md', ]); }; ``` ## Tables Tables are useful for conventions and reference material. | Source | Output | Purpose | | --- | --- | --- | | `.dev/docs/index.md` | `/index.html` | Site landing page | | `.dev/docs/pages/index.md` | `/docs/index.html` | Documentation landing page | | `.dev/docs/pages/guides/configuration.md` | `/docs/guides/configuration.html` | Nested guide page | | `.dev/docs/pages/guides/index.md` | `/docs/guides/index.html` | Nested guide index | ## Horizontal rule A horizontal rule can separate major examples when a heading would be too heavy. --- ## Mixed content A final section combines several Markdown items. 1. Start with a command: ```bash vendor/bin/castor-docs generate ``` 2. Confirm the generated files: - `index.html` - `docs/index.html` - `search-index.json` 3. Open the generated site in a browser. > [!TIP] > Use this page when adjusting theme spacing or typography. It gives quick visual feedback across most supported Markdown elements.
Castor ecosystem