Vdocs

• Requirements
• Screenshot
• Installation
  • Anystack (Composer)
• Filament setup
• Using the plugin
  • Content model
  • Creating content manually
  • Page layouts
  • Documentation settings
  • Public routes
  • Configuration
  • Morph map (required with HasSEO)
  • Blade components
• Importing from VitePress
  • Command
  • What the importer does
  • Expected folder structure
  • Frontmatter support
  • Sidebar groups and order
  • Link rewriting
  • Images and assets
  • Example: Cosmolab
  • After import
  • Re-importing
• Testing
• License

Version 0.0.1 · Paid — source-available (not Open Source)

Filament 5 package for documentation sites: markdown pages, VitePress-style sidebar navigation, table of contents, locales, and optional integration with voodflow/vpress. Requires a Filament 5 admin panel — it does not run as a plain Laravel package without Filament.

#Requirements

• PHP 8.4+
• Laravel 12 or 13
• Filament 5
• ralphjsmit/laravel-filament-seo
• spatie/laravel-markdown

Optional

• voodflow/vpress — VitePress-style site shell (header nav, footer, theme, doc/home layouts)

#Screenshot

Vdocs + Vpress plugins in action

#Installation

#Anystack (Composer)

{
  "repositories": [
    {
      "type": "composer",
      "url": "https://vdocs.composer.sh"
    }
  ],
}

Then run:

composer require voodflow/vdocs
php artisan vdocs:install

vdocs:install publishes configs and migrations for vdocs and its dependencies, runs migrations, and — when voodflow/vpress is installed — updates config/vdocs.php to use vpress layouts.

Options:

php artisan vdocs:install --force          # overwrite published config files
php artisan vdocs:install --skip-migrate   # publish only, run migrate yourself

#Filament setup

Register the plugin in your panel provider:

use Voodflow\Vdocs\VdocsPlugin;

$panel->plugins([
    VdocsPlugin::make(),
]);

After installation, open your Filament panel. The Vdocs navigation group contains:

#Using the plugin

#Content model

vdocs stores documentation in three database tables:

• Sections — logical groups with a URL slug and sort order.
• Pages — markdown content with layout, locale, publication status, and sidebar metadata.
• Settings — global documentation options (cached).

#Creating content manually

1. Create a section (e.g. slug guide, title Guide).

2. Create pages inside that section:

   • slug: URL segment (getting-started, or index for the section landing page)
   • layout: doc (default article), home (hero landing), or page (root-level article without section)
   • status: must be Published to appear on the public site
   • sidebar_group: optional group label in the left sidebar (e.g. Getting Started)
   • sidebar_order / sort_order: control navigation order

3. Write markdown in the Content field. Headings (##, ###, …) automatically feed the on-page table of contents.

#Page layouts

The home layout reads structured data from home_data (hero name/text/tagline, image, action buttons, feature cards). This is populated automatically when importing VitePress layout: home frontmatter, or can be edited in the database.

#Documentation settings

Open Vdocs → Settings:

Home resolution order for /docs:

1. If Site page mode is enabled and a valid published vpress page is selected → render that page.
2. Otherwise → render the selected (or first available) home layout doc page.
3. If no home page exists → redirect to the first section.
4. If there are no sections either → 404.

#Public routes

All routes use the vdocs.locale middleware. Default prefix is docs (configurable).

When vpress is installed and vdocs.nav.show_in_header is true, a Docs dropdown appears in the site header:

• Overview → /docs
• Each section → /docs/{section}

There is no /docs/overview URL — Overview is the label for the docs home.

#Configuration

Publish and edit config/vdocs.php:

When voodflow/vpress is installed, vdocs:install switches layouts to vpress::layouts.* automatically.

#Morph map (required with HasSEO)

If your application uses Relation::enforceMorphMap(), register the doc page model:

'doc_page' => \Voodflow\Vdocs\Models\DocPage::class,

#Blade components

#Importing from VitePress

vdocs includes an Artisan command to migrate an existing VitePress content folder (the directory that contains index.md and section subfolders) into the database.

#Command

php artisan vdocs:import-vitepress /path/to/docs [--force]

Without --force, the command aborts if any documentation pages already exist.

#What the importer does

1. Scans markdown files recursively, skipping .vitepress/ and node_modules/.
2. Parses YAML frontmatter (--- blocks at the top of each file).
3. Creates or updates sections and pages in the database, all marked as published.
4. Rewrites internal links in markdown from VitePress paths (/guide/foo) to vdocs paths (/docs/guide/foo).
5. Rewrites hero action links in home frontmatter the same way.
6. Optionally copies images from .vitepress/dist/assets/ into public/images/ (see below).

#Expected folder structure

A typical VitePress docs tree:

docs/
├── index.md              → home page (layout: home)
├── guide/
│   ├── index.md          → /docs/guide
│   ├── getting-started.md
│   └── first-project.md
├── api/
│   ├── index.md
│   └── daisy-cosmolab.md
└── resources.md          → root-level page (layout: page)

Path → URL mapping:

#Frontmatter support

The importer recognises VitePress frontmatter keys:

---
title: Custom Page Title
layout: home        # home | page (default: doc)
hero:
  name: Product Name
  text: Tagline
  tagline: Subtitle
  image:
    src: /images/logo.png
    alt: Logo
  actions:
    - theme: brand
      text: Get Started
      link: /guide/getting-started
features:
  - icon: 🎛️
    title: Feature title
    details: Feature description
---

If title is omitted, the importer derives it from the VitePress sidebar label or the section/file name.

#Sidebar groups and order

During import, each page receives sidebar_group, sidebar_order, and sort_order from a sidebar index built at import time.

The default sidebar definitions in ImportVitePressCommand mirror the Cosmolab VitePress project (guide, api, examples, hardware, ai). Page titles and sidebar groups match the original VitePress config.mjs sidebar.

For a different VitePress site, update sidebarDefinitions() and sectionDefinitions() in:

src/Console/ImportVitePressCommand.php

Copy the sidebar object from your .vitepress/config.mjs into the same structure, then re-run the import with --force. Alternatively, import once and adjust sidebar groups manually in Filament.

#Link rewriting

Markdown links are rewritten on import:

The prefix follows config('vdocs.prefix') (default docs).

#Images and assets

If you have already built the VitePress site (npm run docs:build), the importer copies matching files from:

{path}/.vitepress/dist/assets/

into public/images/. By default this applies to files whose names start with cosmolab_ or lasercut_.

For other projects, either:

• place images in public/images/ before import and reference them as /images/... in markdown, or
• extend copyDistAssets() in ImportVitePressCommand.php.

Hero images referenced in frontmatter (hero.image.src) are kept as absolute paths (e.g. /images/logo.png).

#Example: Cosmolab

# From the Laravel app container or project root
php artisan vdocs:import-vitepress /path/to/cosmolab-docs --force

Then open /docs in the browser. With vpress installed you should see the hero landing; section pages appear under /docs/{section}/{slug}.

#After import

1. Visit Filament → Vdocs → Settings and confirm the Documentation home page points to the imported index.md home page.
2. Review Pages for any missing sidebar groups or titles.
3. Run npm run build in your Laravel app if vpress frontend assets changed.
4. Clear rendered content cache if you edit pages programmatically: each page clears its own cache on save.

#Re-importing

--force deletes all sections and pages before importing. Settings are preserved. Use this when refreshing content from an updated VitePress tree.

#Testing

cd packages/voodflow/vdocs
composer install
vendor/bin/phpunit

#License

Voodflow Source-Available License — the source is visible for audit and local development, but this is not Open Source. Production use requires a paid license from Voodflow.

The site shell voodflow/vpress is free and Open Source (MIT).