Extension Points#

Inkstone is built from small services connected by contracts and DTOs.

Commands should stay thin. Package behavior lives in services, parsers, transformers, renderers, and generators.

Pipeline Overview#

CompositeDocumentDiscoverer
    ├── FilesystemDocumentDiscoverer (Markdown files)
    └── ApiSpecDiscoverer (OpenAPI spec files)
         -> MarkdownParser (skipped for API documents)
         -> TransformerPipeline
             ├── HeadingAnchorTransformer
             ├── ExternalLinkTransformer
             ├── BaseUrlLinkTransformer
             ├── GitHubRelativeLinkTransformer
             ├── DemoBlockTransformer
             ├── SyntaxHighlightTransformer
             └── ApiHtmlTransformer (generates API page HTML)
         -> NavigationBuilder
         -> DocumentRenderer
         -> StaticSiteGenerator
             -> pages, search, robots metadata, and assets
             -> BuildExtensionPipeline
                 -> configured BuildExtension instances

Core DTOs#

Core Contracts#

Default Services#

Build Extensions#

Build extensions add post-build behavior without modifying the generator. Each extension implements one lifecycle method:

use Inkstone\Contracts\BuildExtension;
use Inkstone\DTOs\BuildContext;

final class BuildManifestExtension implements BuildExtension
{
    public function afterBuild(BuildContext $context): void
    {
        // Inspect $context->documents and $context->pages, then write an artifact
        // beneath $context->outputPath.
    }
}

BuildContext is readonly and exposes:

Extensions run once, in configuration order, after pages, search, robots metadata, and assets are complete. The container resolves each class only when the extension pipeline runs, so constructor injection is available.

StaticSiteGenerator::build() continues to return the rendered pages. Extensions receive the same page list through BuildContext.

Add An Application Extension#

For example, an application can add a small JSON build manifest:

namespace App\Inkstone;

use Illuminate\Filesystem\Filesystem;
use Inkstone\Contracts\BuildExtension;
use Inkstone\DTOs\BuildContext;

final readonly class BuildManifestExtension implements BuildExtension
{
    public function __construct(private Filesystem $files) {}

    public function afterBuild(BuildContext $context): void
    {
        $manifest = json_encode(
            ['pages' => count($context->pages)],
            JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR,
        );

        $this->files->put($context->outputPath.'/build-manifest.json', $manifest."\n");
    }
}

Register it after the bundled sitemap extension:

use App\Inkstone\BuildManifestExtension;
use Inkstone\Extensions\SitemapExtension;

'extensions' => [
    SitemapExtension::class,
    BuildManifestExtension::class,
],

The same configuration works in a standalone inkstone.php loaded with --config when Composer can autoload the extension class. An exception from any extension fails the build through the existing command error handling.

Bundled Sitemap Extension#

SitemapExtension is the first bundled extension and remains in the default configuration. It preserves the existing build.generate_sitemap switch and sitemap.xml output. Laravel applications can resolve it directly to obtain the public sitemap URL:

use Inkstone\Extensions\SitemapExtension;

$url = app(SitemapExtension::class)->url();

See Sitemaps for canonical URL resolution and parent sitemap-index integration.

Transformers#

Default transformers are configured in order:

'transformers' => [
    HeadingAnchorTransformer::class,
    ExternalLinkTransformer::class,
    BaseUrlLinkTransformer::class,
    GitHubRelativeLinkTransformer::class,
    DemoBlockTransformer::class,
    SyntaxHighlightTransformer::class,
    ApiHtmlTransformer::class,
],

Each transformer implements:

use Inkstone\Contracts\Transformer;
use Inkstone\DTOs\Document;

final class AlertTransformer implements Transformer
{
    public function transform(Document $document): Document
    {
        return $document->withHtml($document->html);
    }
}

Register it in the config:

'transformers' => [
    HeadingAnchorTransformer::class,
    AlertTransformer::class,
    SyntaxHighlightTransformer::class,
],

Replacing A Service#

Inside Laravel, bind your implementation in a service provider:

use Inkstone\Contracts\SearchIndexer;

$this->app->bind(SearchIndexer::class, CustomSearchIndexer::class);

Standalone usage can load custom classes through Composer autoloading and config.

Demo Result Renderers#

Inkstone includes individual renderers for exceptions, renderables, primitives, arrays, collections, models, and objects.

Custom result rendering should implement:

use Inkstone\Contracts\DemoResultRenderer;

final class MoneyResultRenderer implements DemoResultRenderer
{
    public function supports(mixed $value): bool
    {
        return $value instanceof Money;
    }

    public function render(mixed $value): string
    {
        return '<p>'.$value->format().'</p>';
    }
}

Keep renderers small and deterministic because they run during static builds.