README

Craft static documentation sites from Markdown with minimal setup.

Docsmith is designed for package and project documentation where you want a fast build flow, a clean default UI, and zero frontend setup.

Features

Build static HTML docs from Markdown
Default output folder is docs for GitHub Pages workflows
Searchable sidebar navigation
Global search results powered by generated search-index.json
Collapsible grouped navigation with active-page auto-open/scroll
Optional right sidebar table of contents
Configurable accent color with Laravel red as the default theme
Syntax-highlighted fenced code blocks
One-click copy button on code snippets
Repository/edit links and previous/next page navigation
Generated search-index.json, sitemap.xml, and .nojekyll artifacts
Optional README index compatibility mode for existing repositories

Installation

composer require --dev mrpunyapal/docsmith

Quick Start

Create a build script (example: build-docs.php):

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Docsmith\Docsmith;

Docsmith::build(
	source: __DIR__ . '/md',
	title: 'My Package Docs',
	description: 'Documentation generated by Docsmith.',
	accentColor: '#ff2d20',
);

Run it:

php build-docs.php

This writes the generated site into docs by default.

Fluent API

<?php

declare(strict_types=1);

require __DIR__ . '/vendor/autoload.php';

use Docsmith\Docsmith;

Docsmith::make()
	->source(__DIR__ . '/md')
	->output(__DIR__ . '/docs')
	->title('My Package Docs')
	->description('Documentation generated by Docsmith.')
	->accentColor('#ff2d20')
	->accentColorDark('#ff6b61')
	->repositoryUrl('https://github.com/acme/package')
	->siteUrl('https://acme.github.io/package')
	->editBranch('main')
	->rightSidebar()
	->baseUrl('/')
	->build();

You can change the accent color at build time. Docsmith derives the softer hover and focus colors from the accent, so hex colors give the best results.

If you need to apply ad-hoc overrides, you can append custom CSS during the build:

Docsmith::make()
	->source(__DIR__ . '/md')
	->output(__DIR__ . '/docs')
	->customCss('body { background: #fff }') // raw CSS
	->build();

Or pass a path to a CSS file which will be appended to assets/app.css:

Docsmith::make()
	->source(__DIR__ . '/md')
	->output(__DIR__ . '/docs')
	->customCss(__DIR__ . '/my-overrides.css')
	->build();

Search Behavior

Docsmith ships two search experiences out of the box:

Sidebar filter search (filters current navigation links)
Global local-index search (queries generated search-index.json and shows clickable results)

The global search index is generated during each build and is static-hosting friendly.

Favicon

Docsmith generates and links a default favicon for every built page. You can override it with a URL, data URI, or a path to a local image file:

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->output(__DIR__ . '/docs')
    ->favicon('https://example.com/favicon.png')
    ->build();

Local favicons are copied into assets/ and linked with the correct relative path for each page.

Open Graph Images

Docsmith can emit og: and twitter: card tags and generate social preview images for you.

Generated images use Node with two packages: Playwright (browser) and capturist (capture runner). Install them once as devDependencies — you do not need to write or maintain a capturist config; Docsmith writes it during the docs build.

npm install -D playwright capturist@^0.1.3
npx playwright install chromium

Requires capturist ≥ 0.1.3 for incremental capture (skip unchanged cards). If Open Graph generation is enabled and these tools (or the Chromium browser) are missing, the docs build fails with the same install instructions.

In CI, install Node deps and Chromium before a docs build that runs capture (or use runCapturist(false) and capture in a later step).

Single default image for all pages

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->title('My Package Docs')
    ->ogGeneratedAll()
    ->build();

This renders one preview card, captures it to docs/og/cover.png, and points every page at it.

Default generated image per page

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->title('My Package Docs')
    ->ogGeneratedPerPage()
    ->build();

Each page gets its own preview at og/<page>.png.

Custom generated template

Pass a file path or raw HTML snippet. The tokens {site_title}, {title}, and {description} are replaced per page:

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->ogTemplate(__DIR__ . '/og-card.html', scope: 'per-page')
    ->build();

The template is rendered inside a 1200×630 shell, so you only need the card markup.

Link to an existing image

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->ogLink('https://example.com/og/cover.png')
    ->build();

The link can be an absolute URL or a root-relative path.

Advanced / low-level

If you prefer, the structured ogImage(...) method exposes every option:

Docsmith::make()
    ->source(__DIR__ . '/md')
    ->ogImage(
        type: 'generated',
        scope: 'per-page',
        template: __DIR__ . '/og-card.html',
        scale: 2,
        viewport: ['width' => 1200, 'height' => 630],
    )
    ->build();

Per-page overrides via frontmatter

Individual pages can override the image, title, or description used in their OG tags:

---
og_image: /assets/page-og.png
og_title: Custom Social Title
og_description: A custom description for social shares.
---

# Page Title

Capture step (advanced)

By default, enabling a generated OG mode runs capture during build().

Capture is incremental via capturist’s built-in cache. Docsmith writes cache into capturist.config.json (manifest at og/.capturist-cache.json). Unchanged preview HTML skips Playwright; rebuilds print Open Graph images up to date.

Force a full regenerate by deleting og/*.png and/or og/.capturist-cache.json, or run capturist with --force.

Skip the capture step (e.g. CI that installs Playwright later):

Docsmith::make()
    ->ogGeneratedAll()
    ->captureOg(false)
    ->build();

Force a full recapture (ignore cache):

Docsmith::make()
    ->ogGeneratedAll()
    ->forceOg()
    ->build();

HTML card previews and capturist.config.json are still written under the output directory so a later capture step can use them.

CI with Open Graph

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'
- run: npm install
- run: npx playwright install chromium --with-deps
- run: php build-docs.php

README Index Compatibility Mode

For repositories that maintain docs links in README sections, you can import that structure directly.

Docsmith::make()
	->readmeIndex(__DIR__ . '/README.md')
	->readmeSkipSections(['Contributing', 'Author', 'Notes'])
	->title('Repository Docs')
	->description('Generated from README index.')
	->build();

Supported list styles include patterns used by:

laravel-undocumented
laravel-attributes-list

Output Model

md/index.md -> index.html
md/installation.md -> installation/index.html
md/guides/configuration.md -> guides/configuration/index.html

If there is no index.md in the source, Docsmith generates a landing page automatically.

GitHub Pages

Because the default output path is docs, a typical package workflow is:

Keep Markdown source in md
Build static site into docs
Publish from docs via GitHub Pages

Development

composer test
composer docs:build

Contributing

Contributions are welcome. Feel free to open issues and pull requests.

License

The MIT License (MIT). See LICENSE for details.

mrpunyapal / docsmith

Maintainers

Package info

Fund package maintenance!

Statistics

Security