Download the PHP package affonsopaulo/manual without Composer

Manual

A Laravel package that turns a directory of Markdown files into a fully-rendered, searchable documentation site — no build step, no Node.js, no database. Drop in your .md files, run one Artisan command, and your docs are live.

Table of Contents

• Introduction
• Installation
• Your First Documentation Page
• Directory Structure
• Front Matter
• Routing
• Navigation
• Images
• Linking Between Pages
• Dynamic Helpers
• Search
• Caching
• Artisan Commands
• Configuration Reference
• Customization

Introduction

Manual scans a directory tree of Markdown files and serves them as a styled documentation site — similar to GitBook or Mintlify, but self-hosted inside your Laravel application. Every URL, navigation item, breadcrumb, previous/next link, and search entry is derived automatically from the file system and optional YAML front matter you add to each file.

Installation

Install the package via Composer:

The package auto-discovers and registers its service provider. You do not need to add anything to config/app.php.

Publish the configuration file when you need to override any default, and publish the compiled assets so browsers can load them:

Your First Documentation Page

The fastest way to get started is to scaffold the default documentation structure:

You will see output like:

Now warm the cache and build the search index:

Visit /manual in your browser — your documentation site is live.

Creating a single page

To add a page without the full scaffold, use manual:make with the path relative to source_path:

This creates docs/manual/guides/authentication.md with a front matter block and an # Authentication Guide heading. See Artisan Commands for all available options.

Directory Structure

The package derives every URL, breadcrumb, and navigation entry directly from the file and directory layout inside source_path (default: docs/manual). No routing configuration is required.

The rules are simple:

• index.md in any directory represents the URL of that directory. getting-started/index.md maps to /manual/getting-started.
• All other .md files map to their filename without the extension. guides/routing.md maps to /manual/guides/routing.
• Nesting is unlimited. Sub-subdirectories follow the same rules recursively.
• The root index.md is the home page (/manual).

Front Matter

Each Markdown file may begin with a YAML front matter block enclosed in --- delimiters. Front matter is optional — the package infers sensible defaults from the file name and content when it is absent.

Available fields

Title resolution order

When no title is set, the package resolves the title in this order:

1. The first # h1 heading in the Markdown body.
2. The filename formatted as a headline (e.g. front-matter.md → Front Matter).

Routing

URLs are derived from the file path relative to source_path. The route prefix (default: manual) is prepended to every URL:

To customize how a specific document's URL is derived, use the slug or url front matter fields — see Front Matter.

Changing the route prefix

Update route_prefix in config/manual.php to serve documentation at a different base URL:

To serve at the application root, set it to an empty string: 'route_prefix' => ''.

Navigation

The sidebar is built automatically from the directory structure. Directories become sections, index.md files become their landing pages, and all other documents become leaf entries.

Pages are sorted by order (ascending) first, then alphabetically. To order a whole section, add order to its index.md.

Pages with hidden: true are excluded from navigation and the search index but remain accessible by URL — ideal for drafts or internal content. Both fields are set in front matter.

Sections

Any directory with an index.md becomes a collapsible section in the sidebar with a dedicated landing page link. A directory without an index.md still groups its children visually but has no link of its own.

Images

Place image files inside the _images directory at the root of your source_path. The package serves them automatically through the same URL prefix and middleware as your documents.

The @image/ alias

Use the @image/ (or @images/) alias to reference any image from any page, regardless of how deeply nested the page is:

The alias always resolves to the configured images directory (default _images), so a page five levels deep does not need ../../../../_images/screenshot.png.

Relative paths

If you prefer relative paths, reference images relative to the current document:

From a page inside a subdirectory (e.g. getting-started/installation.md):

All relative image paths are rewritten to the correct served URL automatically.

External and absolute URLs

URLs starting with a protocol (https://), an absolute path (/), or a data URI (data:) are left unchanged.

Supported extensions

By default: jpg, jpeg, png, gif, webp, svg, ico. Extend or restrict the list in config/manual.php under images.extensions.

Linking Between Pages

Link to other pages using standard relative Markdown links with .md extensions. The package rewrites them to the correct public URL at render time:

Hash fragments are preserved:

Dynamic Helpers

You may embed dynamic URL helpers directly in your Markdown using {{ }} syntax. The package resolves these at render time before converting Markdown to HTML.

Helpers inside code blocks are never resolved. You can safely document the helper syntax itself inside a fenced code block.

route()

Generates a URL for any named Laravel route in your application:

doc()

Generates a URL for a documentation page using its key front matter value. This is stable across URL changes:

The target document must have key: guides.authentication in its front matter.

doc_public()

Generates a URL for a documentation page using its public route path relative to the prefix:

Search

The package exposes a JSON endpoint at /{prefix}/_manual/search.json that powers client-side search. Hidden documents are excluded. Each entry contains:

Configure the endpoint path under search.endpoint in config/manual.php. The path is reserved while search is enabled, so ensure it does not conflict with any document URL.

Caching

The package maintains two independent cache layers.

Manifest cache

Holds the entire scanned document graph: every document descriptor, route lookup tables, and the navigation tree. Its key is derived from the source path and an inventory signature built from the path and modification time of every file. Any file added, removed, or modified automatically invalidates the manifest on the next request.

Page and search cache

Each rendered page is cached individually, keyed on the document's relative path, its modification time, and a fingerprint of the active Laravel routes. The search index is cached under a similar key. Changing a single file invalidates only that file's page cache; the rest of the site remains cached.

Cache configuration

To disable caching locally, set a negative TTL in config/manual.php or point MANUAL_CACHE_STORE to the array driver in .env.

Artisan Commands

manual:init

Scaffolds the default documentation structure in your source_path. Creates an _images directory, a root index.md, and example pages organized in three sections (getting-started, guides, advanced).

manual:make

Creates a single new Markdown document at the given path relative to source_path.

Available options:

Example:

manual:build

Warms the manifest cache, renders and caches every page, and builds the search index. Run this after deploying or after structural changes (new files, renamed files, updated front matter):

manual:clear

Flushes every cache key managed by the package. The next request will re-scan, re-render, and re-cache everything.

Configuration Reference

Customization

Replacing the Blade view

Publish the views, edit resources/views/vendor/manual/page.blade.php, then point the view config key to your customized template:

The view receives these variables:

To replace the compiled CSS and JS entirely, publish the assets and set assets.enabled to false:

Protecting documentation with authentication

Set the middleware config key to add your authentication middleware to every documentation and image route:

Using a different source directory

Point source_path to any directory — both absolute and relative paths (resolved from base_path()) are supported:

Requirements

• PHP 8.5+
• Laravel 12 or 13

License

Manual is open-source software licensed under the MIT license.