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:^0.0.2

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:

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

Statistics

Security