# LaRecipe 3.x

> LaRecipe is the docs engine that lives inside your Laravel app: Markdown docs in your repo (or your database), served to people as a fast site and to agents as Markdown, llms.txt, skill.md and MCP, and kept current by your own coding agent in the same pull request as the code.

Read the 3.x pages unless the user is on LaRecipe 2. Commands are php artisan larecipe:*; configuration lives in config/larecipe.php, presentation in docs/larecipe.json. Prefer the Reference pages for exact option names.

Every page is also available as Markdown: the links below point to it, and adding `.md` to any page URL works too. Search and read these docs with the MCP server at `https://larecipe.saleem.dev/mcp` (tools: search_docs, read_page, list_pages). The full text of this version is at `https://larecipe.saleem.dev/3.x/llms-full.txt`. An agent skill for these docs is at `https://larecipe.saleem.dev/skill.md`. Other versions: 2.x (maintained) at `https://larecipe.saleem.dev/2.x/llms.txt`.

## Introduction

- [Introduction](https://larecipe.saleem.dev/3.x/index.md): LaRecipe is a docs site that lives inside your Laravel app, written and kept current by the coding agent you already use. It has one goal: your docs never fall behind your code, so people and agents always read the current answer.

## Get started

- [Installation](https://larecipe.saleem.dev/3.x/get-started/installation.md): Add LaRecipe to a Laravel app with two commands, and get a working docs site plus the agent setup that keeps it current.
- [Your first docs](https://larecipe.saleem.dev/3.x/get-started/your-first-docs.md): Let the coding agent you already use read your app and write real starter docs for the readers you choose, then review them before anything is committed.
- [Configuration basics](https://larecipe.saleem.dev/3.x/get-started/configuration.md): Where LaRecipe's settings live, the few that most apps change (the URL, who may read, where pages are stored), and how to add a second doc set.

## Writing

- [Project structure](https://larecipe.saleem.dev/3.x/get-started/project-structure.md): What lives in your docs folder, how to add a page, how each file path becomes a URL, and the three frontmatter keys every page starts with.
- [Markdown](https://larecipe.saleem.dev/3.x/writing/markdown.md): Write pages in GitHub-flavored Markdown, link them with relative .md paths, and add alerts and components where plain Markdown falls short.
- [Components](https://larecipe.saleem.dev/3.x/writing/components.md): Every built-in component with a live example and the Markdown that produced it, and which one to use for what.
- [Code blocks](https://larecipe.saleem.dev/3.x/writing/code-blocks.md): Highlighted code with titles, line highlights, line numbers and diffs, and samples included straight from your codebase so they never drift.
- [Navigation](https://larecipe.saleem.dev/3.x/writing/navigation.md): Get a sidebar from your folders with no config, write navigation.json when you want to choose the order and groups, and keep old URLs working with redirects.
- [Versions](https://larecipe.saleem.dev/3.x/writing/versions.md): Serve several versions of your docs side by side, each in its own folder, and start the next one by copying the current one with one command.
- [Languages](https://larecipe.saleem.dev/3.x/writing/languages.md): Serve your docs in more than one language, with right-to-left support, a fallback for pages not yet translated, and a check that finds translations falling behind.

## Keeping docs current

- [How it works](https://larecipe.saleem.dev/3.x/keeping-current/how-it-works.md): Every page lists the code it describes, larecipe:affected maps each change to the pages it made stale, and your coding agent updates them in the same push as the code.
- [Agent instructions](https://larecipe.saleem.dev/3.x/keeping-current/agent-instructions.md): The LaRecipe block in AGENTS.md that tells every AI coding session to update the affected docs before it pushes, with a compact index of your pages, generated from your config.
- [The pre-push hook](https://larecipe.saleem.dev/3.x/keeping-current/pre-push-hook.md): When an agent's push leaves docs pages stale, the hook holds it once and tells the agent which pages to update, plus an optional git hook for people who push without an agent.
- [Skills and the Claude Code plugin](https://larecipe.saleem.dev/3.x/keeping-current/skills.md): The four LaRecipe skills that teach any coding agent to write, update, audit and upgrade your docs, where the installer puts them, and the Claude Code plugin that ships them with the hooks.
- [Review modes](https://larecipe.saleem.dev/3.x/keeping-current/review-modes.md): Choose whether your agent asks before it commits docs changes (required, the default) or updates and pushes them on its own (auto), and what each mode means for changes made outside a pull request.

## For agents

- [Agent surfaces](https://larecipe.saleem.dev/3.x/agents/surfaces.md): Every page as Markdown, llms.txt indexes, a generated skill.md and an MCP server, so agents read the same docs people do, under the same access rules.
- [The MCP server](https://larecipe.saleem.dev/3.x/agents/mcp.md): Connect any MCP client to your docs, over HTTP for your readers' agents or locally for your own coding agent, and see which tools each one gets.
- [Ask AI](https://larecipe.saleem.dev/3.x/agents/ask-ai.md): Let readers ask a question and get a short answer written only from your docs, with every cited page checked, on your own laravel/ai provider key.

## Customize

- [Theme](https://larecipe.saleem.dev/3.x/customize/theme.md): Make the default LaRecipe theme yours with a few tokens in larecipe.json, your logo and, when you need it, a stylesheet of your own.
- [Custom React components](https://larecipe.saleem.dev/3.x/customize/custom-components.md): Write your own components in React, use them in Markdown like the built-ins, and give each one a no-JavaScript fallback and a Markdown form for agents.
- [Insert points and slots](https://larecipe.saleem.dev/3.x/customize/insert-points.md): Add a component to every page at one of seven named positions, opt a page out, and replace a built-in region such as the footer while keeping the original inside it.

## Operate

- [Deployment](https://larecipe.saleem.dev/3.x/operate/deployment.md): Deploy a LaRecipe site like any Laravel app with a four-line script, plus the extra steps for database sets, custom components and UI assets served by your web server.
- [Validation and doctor](https://larecipe.saleem.dev/3.x/operate/validation.md): Check that the docs are correct with larecipe:validate and what agents get from your app with larecipe:doctor, read their reports, and run them in CI.
- [Search](https://larecipe.saleem.dev/3.x/operate/search.md): Search works with no service to run. What gets indexed, how to keep the browser index small, the server driver, and how to plug in your own engine.
- [Analytics and events](https://larecipe.saleem.dev/3.x/operate/analytics.md): Add GA4, Plausible, Fathom, PostHog or your own script from your config, collect page and answer feedback, and forward every request, agents included, to your own tools with Laravel events.

## Advanced

- [Live references](https://larecipe.saleem.dev/3.x/writing/live-references.md): Let a page read routes, artisan commands, models and events from your running app, so those facts cannot go stale.
- [Gate blocks and private docs](https://larecipe.saleem.dev/3.x/writing/gate-blocks.md): Decide who may read a doc set, a version, a page or one paragraph with your app's own auth and gates, applied the same way on every surface people and agents read.
- [The optional CI check](https://larecipe.saleem.dev/3.x/keeping-current/ci-check.md): An optional GitHub Actions check that validates the docs on every pull request and fails or comments when the change leaves pages stale, without running an AI agent or writing anything.
- [larecipe:sync](https://larecipe.saleem.dev/3.x/keeping-current/sync.md): Run a docs agent inside your app on your own AI provider key, on demand, to update the pages a change affected, audit a whole doc set, or edit a production database set outside a pull request.
- [Static export](https://larecipe.saleem.dev/3.x/operate/static-export.md): Write your public docs to a folder of plain files any static host can serve, with search that works offline, and know exactly what a static site leaves out.
- [The repository source](https://larecipe.saleem.dev/3.x/sources/repository.md): The default source. A doc set as Markdown files in your app's own repository, changed in pull requests, with each page's last change read from git.
- [Database and the admin UI](https://larecipe.saleem.dev/3.x/sources/database.md): Keep a doc set in your app's database, always behind a persistent cache, with a revision for every change and an admin UI to manage it.
- [Docs migrations](https://larecipe.saleem.dev/3.x/sources/docs-migrations.md): Ship content changes to a database doc set in the pull request, as migration files that php artisan migrate applies on deploy without ever overwriting a newer edit.
- [Switching sources](https://larecipe.saleem.dev/3.x/sources/switching.md): Move a doc set between the repository and the database at any time, with a dry run first and a hash-by-hash check after, or carry it anywhere as a bundle.
- [Caching](https://larecipe.saleem.dev/3.x/operate/caching.md): How LaRecipe caches rendered pages, page lists, navigation and search records by content, so nothing is ever purged by hand, and what larecipe:optimize and larecipe:clear do.
- [Security](https://larecipe.saleem.dev/3.x/operate/security.md): What LaRecipe does to keep docs content from running code or leaking secrets, applies one access policy to every surface, keeps agents and CI read-only by default, and the cache headers each response carries.

## Reference

- [Artisan commands](https://larecipe.saleem.dev/3.x/reference/commands.md): Every larecipe:* artisan command, grouped by job, with its usage and options read from the running app.
- [Configuration](https://larecipe.saleem.dev/3.x/reference/configuration.md): Every key in config/larecipe.php with its type, default and meaning, which keys a doc set may override, and the environment variables the file reads.
- [Frontmatter](https://larecipe.saleem.dev/3.x/reference/frontmatter.md): Every frontmatter key a page can set, with its type, meaning and an example, how unknown keys are handled, and the schema URL.
- [larecipe.json](https://larecipe.saleem.dev/3.x/reference/manifest.md): Every key of a doc set's manifest, larecipe.json, with its type, meaning and an example, this site's own manifest, and where the schema is served.
- [Components](https://larecipe.saleem.dev/3.x/reference/components.md): The props of every built-in component, the live references, the gate blocks and this site's own components, with what each renders as server HTML and as agent Markdown.
- [Events](https://larecipe.saleem.dev/3.x/reference/events.md): Every Laravel event LaRecipe dispatches, when each one fires, its payload read from the running app, and how the request kind is decided.
- [MCP tools](https://larecipe.saleem.dev/3.x/reference/mcp-tools.md): Every tool, resource and prompt the LaRecipe MCP server exposes, with descriptions, annotations, input schemas and which server offers each one.

## Upgrade

- [Upgrade from v2](https://larecipe.saleem.dev/3.x/upgrade.md): Move a LaRecipe 2 site to LaRecipe 3 with one command and a report, then finish the manual items with your coding agent and the larecipe-upgrade-v2 skill.

## Languages

- [English](https://larecipe.saleem.dev/3.x/llms.txt): en
- [العربية](https://larecipe.saleem.dev/ar/3.x/llms.txt): ar