A doc set can live in your repository or your database, and both keep the same format: Markdown pages with frontmatter, larecipe.json and navigation.json. So moving between them is a copy plus a proof. larecipe:source:move copies a set from one source to the other, checks every content hash when you ask it to, and prints the config change that switches serving. It never edits your config itself.
- See the plan
bash php artisan larecipe:source:move repository database --set=docs --dry-runA dry run copies the set into a temporary bundle, validates every page, and prints how many pages, navigation files and assets will move, with any warnings and validation errors. It writes nothing to the target.
- Move and verify
bash php artisan larecipe:source:move repository database --set=docs --verifyWith
--verify, the command reads everything back from the target and compares the content hash of every page, navigation tree, manifest and asset. It reports that everything matches, or lists each mismatch and exits with an error. - Switch serving
The command ends with the change to make in
config/larecipe.php:config/larecipe.php 'sets' => [ 'docs' => [ 'source' => ['driver' => 'database'], ], ],Make the change, deploy it, and run
php artisan larecipe:cache:warmfor a database set.
The two directions are the two argument orders: repository database, or database repository. Moving the other way prints ['driver' => 'repository', 'path' => base_path('docs')] as the config change.
Where to run it
The move writes to the target on the machine where you run it. To move production's docs into production's database, run it on production before you deploy the config change. To move a database set into your repository, refresh your local database first with larecipe:pull, run the move locally, and commit the files. From then on, provenance comes from git.
Bundles: export and import
A bundle is a doc set written out as canonical files, to a directory or a .tar.gz file, with the same layout as a repository set's folder. Use it for a backup, to hand docs to another app, or to bring a whole set of admin UI edits back into git.
php artisan larecipe:source:export --set=docs --to=storage/docs.tar.gz
php artisan larecipe:source:import storage/docs.tar.gz --set=docs --verifyImport validates every page first and writes nothing if any has an error. Like a move, it adds and updates, and never deletes pages the set already has. To carry only some admin edits through a pull request, export them as a docs migration from the admin's activity screen instead.
Details
Every option of source:move
| Option | Means |
|---|---|
--set |
The doc set. Defaults to larecipe.default. |
--path |
The folder on the repository side, when it is not the configured one. Defaults to docs/ for the default set, and to a folder named after the set otherwise. |
--connection |
The database connection on the database side. |
--dry-run |
Show the plan and the validation, and write nothing. |
--verify |
After writing, read the target back and compare every content hash. |
larecipe:source:moveMove a doc set between the repository and the database source
php artisan larecipe:source:move [--set [SET]] [--path [PATH]] [--connection [CONNECTION]] [--dry-run] [--verify] [--] <from> <to>| Argument | Description | Default |
|---|---|---|
from | The source the set uses now: repository or database (required) | |
to | The source to move it to: repository or database (required) |
| Option | Description | Default |
|---|---|---|
--set=SET | The doc set (default: larecipe.default) | |
--path=PATH | The docs folder on the repository side, when it is not the configured one (default: docs/) | |
--connection=CONNECTION | The database connection on the database side | |
--dry-run | Show the plan and the validation, write nothing | |
--verify | After writing, re-read the target and compare every content hash |
What moves, and in what order
A move copies, in this order:
- The manifest,
larecipe.json. - Every page of every version and language, with its frontmatter and body. Deeper pages go first, so a folder's own page lands as
folder/index.mdin a repository and relative links keep working. - Each navigation, per version. A language's navigation is copied only when it differs from the default language's, because both sources fall back to that one.
- Assets: files in
_assets/and next to pages on the repository side, files on the set's disk on the database side.
Every page is validated before anything is written. If any page has a validation error, nothing is written at all. Content that is already identical in the target is skipped, so running the same move twice writes nothing the second time. Pages the target already holds that the source does not are kept, and the plan warns about them. Every change is recorded as made by larecipe:source:move.
What does not move
- Revision history. Git history and the revisions table are not the same thing, so neither is converted into the other. The plan says so every time: the target starts its own history from the move.
- Drafts and conflicts. Only live content moves. Drafts and unresolved docs migration conflicts stay in the database's revisions table.
- Hand-written skills. A repository set's
skills/folder is not part of a set's content, so it does not move. - Your config. The command prints the change; you make it.
Bundle formats, with this site's export
--to is a new or empty directory, or a file ending in .tar.gz. Archives are packed with PHP's own PharData, so the server needs no tar binary. An import is recorded as made by larecipe:source:import, and --verify compares every content hash afterwards, as a move does. larecipe:pull uses the same bundles to refresh a local database set from production.
Exporting this site's own doc set, while this page was first written, printed:
Manifest (larecipe.json) ........ yes
Pages ........................... 31
Navigation files ................ 2
Assets .......................... 0
INFO Exported the [docs] set to [storage/docs.tar.gz].The archive holds the same paths as this site's docs/ folder, for example:
larecipe.json
2.x/index.md
2.x/navigation.json
3.x/index.md
3.x/navigation.json
3.x/agents/surfaces.md
3.x/ar/index.md
3.x/ar/get-started/installation.mdNext
- The repository source: docs as files, with provenance from git.
- Database and the admin UI: docs in your database, always behind a cache.
- Docs migrations: content changes to a database set, in the pull request.