Inkstone Docs
Search... ⌘K
Reference

Configuration Reference#

This page lists the main inkstone configuration keys.

Paths#

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

Site#

'site' => [
    'title' => env('INKSTONE_TITLE', 'Inkstone Docs'),
    'description' => env('INKSTONE_DESCRIPTION', 'Project documentation generated with Inkstone.'),
    'base_url' => env('INKSTONE_BASE_URL', ''),
    'favicon' => null,
    'logo' => [
        'light' => null,
        'dark' => null,
    ],
    'show_title' => true,
    'footer' => [
        'enabled' => true,
        'text' => 'Built with Inkstone',
        'url' => 'https://mykemeynell.github.io/inkstone',
        'repository' => [
            'url' => env('INKSTONE_GITHUB_REPOSITORY', 'https://github.com/mykemeynell/inkstone'),
            'label' => 'Repository',
        ],
    ],
],

base_url defaults to the served root. Set it only when the generated site is mounted below a URL path such as /docs or /my-package.

favicon and logo can be explicit URLs or null for source-level discovery. logo accepts a string or an array with light and dark keys for separate logo variants per theme mode.

The footer can be disabled or customized from site.footer. Set site.show_title to false to hide the site title from the header brand. site.footer.repository.url controls the repository link shown next to the footer text; omit or set to an empty string to remove it. site.footer.repository.label customises the link text.

Laravel Routes#

'routes' => [
    'domain' => env('INKSTONE_ROUTE_DOMAIN'),
    'path' => env('INKSTONE_ROUTE_PATH', 'docs'),
    'middleware' => [],
],

Call Inkstone::routes() from routes/web.php to serve generated output from the Laravel application. routes.path controls the mount path, routes.domain restricts docs to a specific host, and routes.middleware adds middleware only for the documentation routes.

The route server reads from output_path and does not build docs during requests. When serving through Laravel, Inkstone adjusts generated root-relative URLs to the configured route path. Use site.base_url for static-host deployments where the generated files themselves need a deploy path such as /my-package.

Theme#

'theme' => [
    'name' => 'default',
    'layout' => 'default',
    'default_mode' => 'system',
    'syntax_highlighting' => [
        'enabled' => true,
        'theme' => [
            'light' => \Phiki\Theme\Theme::GithubLight,
            'dark' => \Phiki\Theme\Theme::GithubDark,
        ],
        'show_line_numbers' => true,
        'copy_button' => true,
    ],
],

theme.name selects the CSS variable file loaded after the base stylesheet. theme.layout selects the Blade layout view. theme.default_mode sets the initial color mode (system, light, or dark).

Syntax highlighting is powered by Phiki and occurs at build time.

Markdown#

'markdown' => [
    'unsafe_links' => false,
    'html_input' => 'allow',
    'renderer' => [
        'soft_break' => "\n",
    ],
],

Inkstone registers CommonMark core, GitHub Flavored Markdown, and footnotes.

'navigation' => [
    'expanded' => [],
],

Navigation ordering comes from frontmatter order. The expanded key controls which sidebar sections start expanded: set to true (all expanded), false (only the active section), or an array of slugs to expand specific sections.

Discovery#

'discovery' => [
    'ignore' => [
        'vendor',
        'node_modules',
        'build',
        'storage',
    ],
],

Inkstone discovers .md and .markdown files recursively.

'search' => [
    'enabled' => true,
    'driver' => env('INKSTONE_SEARCH_DRIVER', 'json'),
    'max_content_length' => 5000,
    'type' => 'input',
    'drivers' => [
        'json' => [ ... ],
        'lunr' => [ ... ],
        'algolia' => [ ... ],
        'typesense' => [ ... ],
    ],
],

search.type controls the search trigger UI: 'input' shows a search box with keyboard shortcut badge, 'button' shows an icon button.

Inkstone supports multiple search drivers. Local drivers (json, lunr) generate an index file, while remote drivers (algolia, typesense) push data directly to their respective APIs.

GitHub#

'github' => [
    'repository' => env('INKSTONE_GITHUB_REPOSITORY', '...'),
    'branch' => env('INKSTONE_GITHUB_BRANCH', 'main'),
    'rewrite_relative_links' => true,
    'rewrite_images' => true,
],

Relative repository links are rewritten to raw GitHub URLs.

Build#

'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',
    'assets' => [
        'additional_paths' => [ ... ],
        'dist_path' => null,
        'manifest_path' => null,
    ],
],

check_links validates internal <a href> links at build time and fails the build when broken links are found. Set check_links_level to 'warn' to report broken links without failing.

generate_sitemap is the backwards-compatible switch used by the bundled SitemapExtension. It remains enabled by default and writes sitemap.xml. Configure an absolute site.base_url for a standards-compliant static sitemap; Laravel builds can also resolve relative bases against the application URL or infer the named Inkstone route. See Sitemaps.

Extensions#

use Inkstone\Extensions\SitemapExtension;

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

Extensions are resolved lazily from the container and invoked once in declaration order after pages, search, robots metadata, and assets have been written. This supports constructor injection in Laravel and in standalone --config builds. Keep SitemapExtension::class in the list to retain the default sitemap behavior; add application extensions after or before it according to their post-build dependency.

Demos#

'demos' => [
    'enabled' => true,
    'execute_php' => true,
    'execute_blade' => true,
    'describe_void_output' => false,
    'use_disposable_database' => false,
    'database' => [
        'connection' => 'inkstone_demo',
        'database' => ':memory:',
    ],
    'show_stack_traces' => false,
    'sandbox' => [
        'enabled' => true,
        'timeout' => 5,
        'memory_limit' => '128M',
        'allow_filesystem_writes' => false,
        'allow_process_execution' => false,
    ],
],

Demo blocks are static build-time examples. describe_void_output controls whether void demo output is described textually. use_disposable_database creates an in-memory SQLite database per demo. database configures the database connection. show_stack_traces controls stack trace rendering for demo exceptions.

API#

'api' => [
    'enabled' => true,
    'spec_filenames' => [
        'openapi.yaml',
        'openapi.yml',
        'openapi.json',
    ],
    'base_path' => 'api',
    'generate_code_examples' => true,
],

When enabled, Inkstone searches the documentation source directory for files matching spec_filenames. Each discovered spec is parsed by cebe/php-openapi and rendered as an API reference page under the base_path URL prefix. The generated page includes endpoint groups by tag, parameter tables, request body schemas, response codes, and component schemas.

Set enabled to false or use the --no-api CLI flag to disable API documentation for a build.

Local Server#

'server' => [
    'host' => '127.0.0.1',
    'port' => 8080,
],

Used by docs:serve.