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.

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:

1. Keep Markdown source in md
2. Build static site into docs
3. 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.