Vtuts

• Requirements
• Optional dependencies
• Screenshots
• Installation
  • From GitHub (Composer)
  • vtuts:install
• Core concepts
• Markdown authoring
  • Document structure
  • Headings and table of contents
  • Inline code and code blocks
  • Callouts (alerts)
  • Tables, lists, and GFM extras
  • Introduction deduplication
  • Default template
• Tutorial series (learning paths)
  • Admin workflow
  • Public URLs
  • MCP: sync_vtut_series_lessons
• Filament admin
  • Shield roles and tutorial visibility
  • SubKit + Stripe (optional paid access)
• Configuration
  • Standalone frontend
  • With vpress
• Public routes
• Tutorial page layout
• Multilingual content
• Sitemap
• MCP server (AI authoring)
  • How it works
  • Setup (out of the box)
  • MCP tools
  • Optional server code roots
  • Environment variables
• Testing
• Features
• License

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

Filament 5 package for technical tutorials: markdown, table of contents, materials, tools, resources, SEO, translations, comments, learning paths (series), and optional public routes. Requires a Filament 5 admin panel in your Laravel 12+ / 13+ app. Pair with voodflow/vpress for a VitePress-style public frontend, or use the bundled standalone theme CSS for a minimal public layout.

#Requirements

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

#Optional dependencies

#Screenshots

Full tutorial in a Serie with progression bar

Full Serie with progress bar

List of all Series

Full tutorial (not from the Series)

List of all tutorials with filter

#Installation

#From GitHub (Composer)

Add the Voodflow repository to your Laravel app composer.json:

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

Then run:

composer update voodflow/vtuts
php artisan vtuts:install

#vtuts:install

The install command publishes configs and migrations for tutorials and its dependencies, patches known relaticle/comments migration issues for MySQL, publishes Filament Shield assets when installed, seeds the default Style guide markdown template, then runs migrate.

php artisan vtuts:install

Options:

When Filament Shield is installed, vtuts:install publishes Shield/permission assets, runs migrations, then offers to create the tutorials role matrix.

You can also run the role setup manually:

php artisan vtuts:shield-roles --generate --super-admin=1

Add HasRoles to your User model when using Shield:

use Spatie\Permission\Traits\HasRoles;

class User extends Authenticatable
{
    use HasFactory, HasRoles, Notifiable;
}

#Core concepts

Vtuts separates what you teach (content) from how it is organised (taxonomy and paths).

A tutorial can belong to one category, appear in one or more series, and link to next steps (other tutorial IDs shown at the end of the article).

Category vs series

• Category = “what kind of tutorial is this?” (used on the listing page and category archives).
• Series = “what order should I read these in?” (course bar, prev/next, progress tracking).

Example: category C++, series C++ Basics containing lessons mapped to examples/cpp/01_basics/* in your project docs.

#Markdown authoring

Tutorial bodies are written in GitHub Flavored Markdown. The renderer (VtutMarkdown) adds VitePress-style callouts and enhanced code blocks.

#Document structure

Use ## for main sections (they appear in the right-hand On this page outline). Use ### for subsections.

#Headings and table of contents

## Overview

## What you need

## Build and flash

### Compile

### Upload to the board

Headings ## and ### receive stable anchor IDs and appear in the doc aside TOC.

#Inline code and code blocks

Wrap commands, filenames, and identifiers in backticks:

Install `arm-none-eabi-gcc`, then run `make program-dfu`.

Fenced blocks with a language tag get syntax highlighting (Shiki), a language label, line numbers, and a copy button (when voodflow/vpress is installed):

```bash
cd examples/cpp/01_basics/CosmoBlink
make clean && make
```

```cpp
#include "daisy_cosmolab.h"

DaisyCosmolab hw;
```

Supported languages follow Spatie Markdown / Shiki (e.g. bash, cpp, ini, python, json).

#Callouts (alerts)

GitHub-style alerts render as coloured boxes with icons:

> [!NOTE]
> Install the toolchain before continuing.

> [!TIP]
> Compare with the next example in the same folder.

> [!IMPORTANT]
> Run `install.bat` on Windows instead of `install.sh`.

Also supported: > [!WARNING].

Legacy blockquote syntax still works:

> **Important note:** Your safety message here.

#Tables, lists, and GFM extras

• Tables — standard pipe tables
• Task lists — - [x] Done / - [ ] Todo
• Strikethrough — ~~removed~~
• Links and images — standard markdown

#Introduction deduplication

If the introduction paragraph is repeated at the start of the content body, it is automatically removed from the displayed body so it does not appear twice on the public page.

#Default template

vtuts:install seeds a Style guide template (slug: style-guide) with all common patterns. In Filament, pick From template when creating a tutorial, or fetch it via MCP (get_vtut_template).

#Tutorial series (learning paths)

Series group tutorials into ordered lessons — like a course or a chapter sequence.

#Admin workflow

1. Create tutorials (draft or published).
2. Tutorials → Series — create a series (title, slug, description, locale).
3. Attach lessons and drag to reorder (or use MCP sync_vtut_series_lessons).

#Public URLs

When features.series is true (default):

Series lesson pages show a course bar: progress, previous/next lesson, and the full lesson list. Authenticated users can persist progress (POST …/progress).

Visibility gates (registered / subscriber) apply to series lesson routes the same way as standalone tutorials.

#MCP: sync_vtut_series_lessons

Replaces the entire ordered lesson list for a series (not incremental append):

{
  "series_slug": "cpp-basics",
  "locale": "en",
  "lesson_slugs": ["cosmoblink", "cosmo-display"]
}

Lesson 1 → cosmoblink, lesson 2 → cosmo-display. Call again with the full ordered list when you add or reorder lessons.

#Filament admin

Register the plugin in your panel provider:

use Voodflow\Vtuts\VtutsPlugin;

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

When bezhansalleh/filament-shield is installed, VtutsPlugin automatically registers:

• FilamentShieldPlugin
• UserResource (CRUD users with role assignment)

Disable Shield integration:

VtutsPlugin::make()->shield(false);

Or in config/vtuts.php:

'shield' => [
    'enabled' => env('VTUTS_SHIELD_ENABLED', true),
    'setup_on_install' => true,
],

Admin resources: Tutorials, Templates, Categories, Series, Tags, Settings, and optionally Users + Shield Roles.

Settings includes listing page copy, pagination, sidebar, read tracking, access-gate URLs, and MCP defaults (author email, draft vs publish, optional server code roots).

#Shield roles and tutorial visibility

Tutorial visibility (per article):

Typical assignments:

• Staff who write tutorials → editor
• Users who sign up on the site → registered
• Paying members → subscriber
• Project owner → super_admin

Customize role names and permission subjects in config/vtuts.php under shield.roles.

#SubKit + Stripe (optional paid access)

When SubKit and Laravel Cashier are installed:

composer require karpovigorok/subkit laravel/cashier
php artisan vtuts:install

Disable SubKit integration:

VtutsPlugin::make()->subkit(false);

#Configuration

Publish and edit config/vtuts.php:

#Standalone frontend

php artisan vendor:publish --tag=vtuts-assets

Public comments use Relaticle. Add the commenter trait to your user model:

use Voodflow\Vtuts\Concerns\CanComment;

class User extends Authenticatable
{
    use CanComment, HasFactory, Notifiable;
}

#With vpress

php artisan vpress:install

That updates config/vtuts.php to use vpress layouts and wires the language switcher. Manual override:

return [
    'layout' => 'vpress::layouts.page',
    'doc_layout' => 'vpress::layouts.doc',
];

With vpress you get shared nav/footer, theme.css via Vite, and enhanced code blocks (vp-code-block with copy button).

#Public routes

Registered when features.public_routes is true:

Set prefix in config/vtuts.php (or VTUTS_PREFIX in .env). Route names stay vtuts.*.

Middleware:

• vtuts.locale — sets app()->getLocale() from the URL
• vtuts.visible — visibility gate for registered/subscriber content

#Tutorial page layout

Doc-style pages include:

• Left sidebar — latest tutorials from the same category, or series lesson list on series URLs
• Main column — title, meta, video, markdown, materials/tools/resources, comments
• Right aside — table of contents, section anchors, comments link, deduplicated external links from materials/tools/resources

#Multilingual content

1. Configure locales and default_locale
2. Enable features.localization
3. Create translations in Filament (Translate action)
4. Default locale: /tutorials/...; others: /{locale}/tutorials/...
5. SEO hreflang alternates per tutorial

Admin UI strings: resources/lang/{locale}/admin.php (English and Italian included).

#Sitemap

use Spatie\Sitemap\Sitemap;
use Voodflow\Vtuts\Support\VtutSitemapGenerator;

Sitemap::create()
    ->pipe(fn ($sitemap) => VtutSitemapGenerator::addToSitemap($sitemap))
    ->writeToFile(public_path('sitemap.xml'));

#MCP server (AI authoring)

Install the optional dependency:

composer require laravel/mcp

Vtuts registers VtutsServer automatically:

• HTTP — {APP_URL}/mcp/vtuts (default route)
• Stdio — php artisan mcp:start vtuts (local process transport)

#How it works

MCP is the publish button for your AI agent — not a code editor.

1. You work on source material in your AI tool (open files, pasted code, conversation).
2. The agent composes tutorial markdown (headings, code blocks, callouts).
3. MCP tools save the result to this site's database (create_vtut, series tools, etc.).

The AI agent already sees your workspace. You do not need to mount external repositories or configure code roots for the typical workflow.

#Setup (out of the box)

1. Admin → Tutorials → Settings → MCP
   • Default author email (staff user that owns AI-created tutorials)
   • Publish immediately vs save as draft (draft recommended)
   • Optional: enable server-side code roots (off by default)
2. Run php artisan vtuts:mcp-info and copy the configuration snippet into your MCP client.
3. Reconnect the MCP client in your AI tool.

{
  "mcpServers": {
    "vtuts": {
      "url": "https://your-site.test/mcp/vtuts"
    }
  }
}

For local development, use your local APP_URL (e.g. http://localhost:8002/mcp/vtuts). The site must be running and reachable.

#MCP tools

create_vtut saves drafts by default unless publish: true or Settings → MCP → Publish tutorials immediately is enabled.

#Optional server code roots

Enable only when the AI agent runs without workspace context and must read files on the server (e.g. a cloned repo at /var/www/myproject).

• Admin → Settings → MCP → Enable server-side code roots
• One absolute path per line
• Activates search_project_code and read_project_file

Leave disabled for normal use: the agent reads from the conversation instead.

#Environment variables

#Testing

composer install
./vendor/bin/phpunit

#Features

• Filament CRUD with drafts, scheduling, bulk publish/unpublish
• Translation groups with per-locale slugs
• Markdown TOC, GitHub alerts, GFM tables, Shiki code blocks
• Materials, tools, resources sidebars with deduplicated aside links
• Tutorial series with ordered lessons and progress tracking
• SEO (Filament + schema.org TechArticle)
• Public comments via Relaticle
• Optional Filament Shield + Users resource
• Standalone dark/light theme with bundled CSS
• MCP tools for AI-assisted authoring
• vpress dynamic block: Latest tutorials

#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. See LICENSE and docs.voodflow.com.

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