Getting Started

The package turns a folder of Markdown files into structured, AI-consumable documentation (an llms.txt-style index plus per-page raw Markdown endpoints).

composer require phattarachai/laravel-ai-docs
php artisan vendor:publish --tag="ai-docs-config"

Then create your docs root (typically docs/ or resources/docs/) and add a root index.md. Hit the configured route (check config/ai-docs.php for the prefix and the index route name) and you should get the generated index back.

Where to look first:

The README's config snippet — it lists every config key, and the published config file is the source of truth for paths, route prefix, middleware, and caching.
The service provider's route registration — confirms exactly which URIs are exposed and what middleware wraps them.
The docs/ directory convention — front matter keys (title, order, group) drive both navigation and the index output.

First use case: expose your product or internal runbook docs to an AI assistant. Point it at the index endpoint, let it discover pages, then have it fetch individual pages as raw Markdown. That is the whole value proposition — no scraping, no HTML-to-text loss.

Start with a three-folder structure so you exercise grouping and nesting on day one rather than retrofitting it later:

docs/
├── index.md
├── getting-started/
│   ├── index.md
│   ├── installation.md
│   └── configuration.md
└── api/
    ├── index.md
    └── authentication.md

Implementation Patterns

Folder labels via `index.md` `group` front matter (new in v1.5.0)

This is the headline change and it removes the main structural wart from earlier versions. Each folder's index.md can now declare its display label:

---
group: Getting Started
order: 1
---

The practical win: the folder name stays a clean slug (getting-started) while the label stays human-readable (Getting Started). Before this, you either lived with Getting-Started in the nav or invented a mapping table in config.

Patterns that fall out of it:

Rename folders freely. Folder names are now purely URL/identity; labelling is content. Renaming misc/ to other/ no longer forces a nav copy change — but it does change URLs, so treat slugs as a public API once an agent has cached them.
Explicit ordering. Pair group with order in the folder's index.md so sections sort deliberately instead of alphabetically.
Fallback behaviour. A folder whose index.md has no group should fall back to the folder name or page title — verify this in your own tree, because a partially-labelled docs folder is the most likely source of a confusing nav.
index.md is a descriptor, not just a page. Treat it as the folder's cover sheet: label, order, and optionally the overview prose that renders as the section landing page.

Front matter per page

Keep page front matter minimal and consistent — title and order are the workhorses. Anything you add becomes a schema you have to maintain across hundreds of files, so resist custom keys unless you actually render them.

Wiring docs into AI tooling

The typical integration is two-step discovery:

Fetch the index endpoint → get a grouped list of pages with titles and URLs.
Fetch individual pages for just the sections relevant to the user's question.

Feed step 1 into the system prompt or tool schema; expose step 2 as a tool call. Because output is Markdown rather than HTML, you skip a stripping/preprocessing step entirely.

Serving internal docs safely

Put auth middleware on the whole route group via config if the docs describe internal APIs, schemas, or incident runbooks. Do this before the first deploy — it is far easier than retrofitting after something is indexed.

Caching and deploys

Generate/cache the index in your deploy pipeline rather than per-request, and warm it as a build step. Doc content changes on deploy, not at runtime, so a cache keyed to the deploy is correct and cheap.

Gotchas and Tips

Front matter must be the first bytes in the file. A leading blank line, an HTML comment, or a UTF-8 BOM above the --- block silently kills parsing and the file renders as a page with no title/group.
Quote values containing colons. group: API: Reference fails or truncates. Use group: "API: Reference".
Duplicate group labels merge. If two folders both declare group: Guides, they will almost certainly collapse into one nav group. Intentional when you want it, baffling when you don't — prefix labels (Guides: Billing, Guides: Shipping) if merging isn't the goal.
Cache invalidation is the #1 support ticket. Edited Markdown, unchanged output. Clear the docs cache (or disable caching in local) after every content edit; wire a watcher or a composer/artisan script if you iterate on docs frequently.
index.md double duty. If the same file both labels the folder and renders as the section landing page, expect it to appear in listings too. Confirm whether it's excluded from the page list and adjust your expectations for "N pages" counts.
Route collisions. A catch-all route (/{any}) defined earlier in the stack will swallow your docs prefix. Check route order with php artisan route:list when you get 404s on one file but not others.
Read-only filesystems in containers. Don't let the package write cache into the docs source directory — point any cache path at storage/. Docs mounted as a read-only volume will otherwise fail with a permission error that looks like a missing-file error.
Slug stability. URLs are derived from filenames. Renaming setup.md → installation.md breaks every external link and every agent that cached the index. Add redirects or accept the churn knowingly.
Fenced code inside docs about docs. A Markdown example showing a fenced block needs four backticks on the outer fence. This bites exactly on the pages documenting the front matter format.
Extension points to reach for: published config (paths, prefix, middleware, caching), published views if you render HTML anywhere, and the folder-level index.md itself as a lightweight per-section config surface. Prefer these over forking the package — the front matter schema is the intended customisation seam and v1.5.0 widened it.

Laravel Ai Docs Laravel Package