Package Author Workflow#

Use this workflow when a package repository wants to replace README-only documentation with a static Inkstone site.

1. Install Inkstone#

composer require mykemeynell/inkstone --dev

Inkstone can run without a Laravel application:

vendor/bin/inkstone docs:install --source=docs --output=build/docs

For a Laravel package testbench application, the Artisan command is also available:

php artisan docs:install

2. Move Existing Docs#

Keep your existing README as the entry point:

docs/
  README.md
  installation.md
  configuration.md

Inkstone treats README.md and index.md as section index pages and generates pretty URLs by default.

3. Add Frontmatter Where Order Matters#

---
title: Installation
order: 2
---

Use order for important pages. Pages without an order fall back to alphabetical ordering.

4. Configure GitHub Rewriting#

Set the repository and branch when your Markdown links to source files:

DOCS_GITHUB_REPOSITORY=https://github.com/vendor/package
DOCS_GITHUB_BRANCH=main

Relative links such as LICENSE.md and images such as assets/screenshot.png are rewritten to GitHub raw URLs during the static build.

5. Build And Preview#

vendor/bin/inkstone docs:build --source=docs --output=build/docs
vendor/bin/inkstone docs:serve --source=docs --output=build/docs --watch

The generated build/docs directory is static. Commit your source Markdown and configuration, not the generated output.

6. Deploy#

Publish build/docs to any static host. GitHub Pages, Netlify, Cloudflare Pages, and Vercel examples are documented in Static Hosting.

For GitHub Pages under a repository path, pass the base URL:

vendor/bin/inkstone docs:build --source=docs --output=build/docs --base-url=/package-name