Configuration#

Inkstone works without configuration, but configuration lets you customize paths, branding, GitHub rewriting, search, themes, syntax highlighting, demo blocks, and generated metadata.

Configuration Files#

Inside Laravel, the config file is:

config/inkstone.php

For standalone usage, create either:

inkstone.php
config/inkstone.php

You can pass a config file explicitly:

vendor/bin/inkstone docs:build --config=inkstone.php

Minimal Config#

<?php

return [
    'source_path' => __DIR__.'/docs',
    'output_path' => __DIR__.'/build/docs',
    'site' => [
        'title' => 'My Documentation',
        'description' => 'Documentation generated by Inkstone.',
        'base_url' => '',
    ],
];

base_url defaults to the served root. Set it to a path such as /docs only when the generated site is hosted below that path.

Source And Output#

source_path is the Markdown source directory:

'source_path' => base_path('docs'),

output_path is the generated static site directory:

'output_path' => base_path('build/docs'),

In standalone config files, prefer __DIR__:

'source_path' => __DIR__.'/docs',
'output_path' => __DIR__.'/build/docs',

Site Metadata#

'site' => [
    'title' => 'Package Documentation',
    'description' => 'Documentation for a Laravel package.',
    'base_url' => '',
    'favicon' => null,
    'logo' => [
        'light' => null,
        'dark' => null,
    ],
],

If favicon or logo are null, Inkstone looks for source-level assets. logo accepts a string or an array with light and dark keys for separate logo variants per theme mode.

docs/favicon.ico
docs/favicon.svg
docs/favicon.png
docs/logo.svg
docs/logo.png
docs/logo.jpg
docs/logo.jpeg
docs/logo.webp

Discovered files are copied into the generated output and linked from the theme.

Theme Settings#

'theme' => [
    'name' => 'default',
    'layout' => 'default',
    'default_mode' => 'system',
],

theme.name selects the CSS variant. theme.layout selects the Blade layout, so bundled variants such as ember and forest can use the default layout. theme.default_mode sets the initial color mode (system, light, or dark).

Build Settings#

'build' => [
    'clean_output_before_build' => true,
    'pretty_urls' => true,
    'generate_sitemap' => true,
    'generate_robots_txt' => true,
    'asset_hashing' => true,
    'check_links' => true,
    'check_links_level' => 'error',
],

With pretty_urls enabled, docs/installation.md becomes:

build/docs/installation/index.html

Asset Settings#

'build' => [
    'assets' => [
        'additional_paths' => [
            resource_path('docs-assets'),
        ],
    ],
],

Additional asset directories are copied into build/docs/assets. Source-level image files are always copied during the build.

Transformers#

The transformer order is configurable:

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

Order matters. Demo blocks are expanded before syntax highlighting so generated demo source and output code can be highlighted.

BaseUrlLinkTransformer rewrites root-relative links to include the configured base_url. It runs before GitHubRelativeLinkTransformer so relative links are handled independently.