README

A Nuxt Content-compatible content management system for Laravel + Inertia.js + Vue applications. Write Markdown, get Vue components, query with Laravel – all with build-time compilation and zero runtime overhead.

Latest Version: v1.0.0 (Stable)

Why Inertia Content?

Traditional CMS solutions force you to pass HTML through Inertia props or parse Markdown at runtime. Inertia Content takes a different approach: compile Markdown to Vue components at build time, while Laravel maintains full control over routing and access.

Key Benefits

• 📝 File-based content - Write Markdown files, get compiled Vue components
• ⚡ Build-time compilation - Zero runtime parsing, optimal performance
• 🔍 Powerful queries - Nuxt Content-style query API in PHP
• 🎯 Full TypeScript support - Type safety from PHP to Vue
• 🔥 Hot Module Replacement - Instant updates during development
• 🎨 Familiar API - If you know Nuxt Content, you already know this
• 🔐 Laravel-first - Server-side access control and routing
• 🚀 Production-ready - Caching, optimization, and security built-in

Installation

Inertia Content is a single Composer package that includes both PHP and JavaScript code.

# 1. Install via Composer
composer require farsi/inertia-content

# 2. Install JavaScript dependencies (IMPORTANT!)
cd vendor/farsi/inertia-content && npm install && cd -

# 3. Run installer
php artisan inertia-content:install

The JavaScript/Vue components are TypeScript source files that your Vite will compile - no pre-built JavaScript.

📖 See How It Works for detailed explanation.

Setup

1. Add Vite Plugin

Add the Vite plugin to your vite.config.ts:

import { defineConfig } from 'vite'
import laravel from 'laravel-vite-plugin'
import vue from '@vitejs/plugin-vue'
import inertiaContent from './vendor/farsi/inertia-content/resources/js/vite'

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true,
    }),
    vue(),
    inertiaContent(),
  ],
  resolve: {
    alias: {
      '@inertia-content': '/vendor/farsi/inertia-content/resources/js'
    }
  }
})

2. Create Content

Create markdown files in resources/content:

---
title: Getting Started
description: Learn how to use Inertia Content
order: 1
---

## Introduction

Welcome to **Inertia Content**!

3. Add Routes

Add content routes to routes/web.php:

use Farsi\InertiaContent\Facades\Content;

Route::get('/docs/{path?}', function ($path = 'index') {
    return Content::pageOrFail("docs/$path");
})->where('path', '.*');

4. Render Content

Create a Vue component to render content:

<script setup lang="ts">
import { ContentDoc } from '@inertia-content'
import { usePage } from '@inertiajs/vue3'

const page = usePage()
</script>

<template>
  <ContentDoc :content-key="page.props.contentKey" />
</template>

Usage

Query Content (PHP)

use Farsi\InertiaContent\Facades\Content;

// Find a single entry
$entry = Content::find('docs/intro');

// Check if content exists
if (Content::exists('docs/intro')) {
    // ...
}

// Query multiple entries
$entries = Content::query()
    ->where('_dir', 'docs')
    ->where('draft', false)
    ->orderBy('order', 'asc')
    ->get();

// Get navigation tree
$nav = Content::navigation('docs');

Render Content (Vue)

ContentRenderer Component

Simple content rendering:

<script setup lang="ts">
import { ContentRenderer } from 'farsi-inertia-content'
</script>

<template>
  <ContentRenderer content-key="docs/intro" />
</template>

ContentDoc Component

Full document with header, TOC, and footer:

<script setup lang="ts">
import { ContentDoc } from 'farsi-inertia-content'
</script>

<template>
  <ContentDoc content-key="docs/intro">
    <template #header="{ meta }">
      <h1>{{ meta.title }}</h1>
      <p>{{ meta.description }}</p>
    </template>

    <template #toc="{ headings }">
      <nav>
        <a v-for="h in headings" :key="h.id" :href="`#${h.id}`">
          {{ h.text }}
        </a>
      </nav>
    </template>
  </ContentDoc>
</template>

ContentList Component

List multiple content entries:

<script setup lang="ts">
import { ContentList } from 'farsi-inertia-content'
import { Link } from '@inertiajs/vue3'
</script>

<template>
  <ContentList :entries="$page.props.entries">
    <template #default="{ entries }">
      <article v-for="entry in entries" :key="entry._id">
        <Link :href="`/${entry._path}`">
          <h2>{{ entry.title }}</h2>
          <p>{{ entry._excerpt }}</p>
        </Link>
      </article>
    </template>
  </ContentList>
</template>

useContent Composable

For advanced use cases:

<script setup lang="ts">
import { useContent } from 'farsi-inertia-content'

const { component, meta, headings, isLoading, error } = useContent('docs/intro')
</script>

<template>
  <div v-if="isLoading">Loading...</div>
  <div v-else-if="error">Error: {{ error.message }}</div>
  <div v-else>
    <h1>{{ meta.title }}</h1>
    <component :is="component" />
  </div>
</template>

Frontmatter

Supported frontmatter fields:

---
title: Page Title              # Required
description: Page description  # Optional
draft: false                   # Optional, default: false
navigation: true               # Optional, default: true
order: 1                       # Optional, for sorting
excerpt: Custom excerpt        # Optional, auto-generated if not provided
# ... any custom fields
---

Configuration

Publish the configuration file:

php artisan vendor:publish --tag=inertia-content-config

Available options in config/inertia-content.php:

return [
    'content_dir' => resource_path('content'),
    'manifest_path' => public_path('build/inertia-content-manifest.json'),
    'show_drafts' => env('INERTIA_CONTENT_SHOW_DRAFTS', false),
    'default_component' => 'Content/Page',
    // ... more options
];

Commands

# Install the package
php artisan inertia-content:install

# Clear content cache
php artisan inertia-content:clear

Testing

# PHP tests
composer test

# JavaScript tests
npm test

How It Works

Inertia Content follows a unique architecture that respects both Laravel and Inertia.js philosophies:

Build Time

1. Vite plugin scans resources/content/**/*.md
2. Parses frontmatter, extracts headings, generates excerpts
3. Compiles Markdown → Vue components
4. Generates JSON manifest with metadata

Runtime

1. Laravel queries the manifest (cached)
2. Passes only the content key through Inertia (never HTML/Markdown)
3. Vue dynamically imports the pre-compiled component
4. Component renders instantly (already compiled)

Key Innovation

No HTML through Inertia props. No runtime Markdown parsing.

Laravel maintains authority over:

• ✅ Content queries and filtering
• ✅ Access control and permissions
• ✅ Routing decisions

Vue handles:

• ✅ Component rendering (pre-compiled)
• ✅ User interactions
• ✅ Client-side navigation

Comparison

Nuxt Content Compatibility

This package implements 80% of Nuxt Content v2 core features, adapted for Laravel + Inertia:

✅ Implemented:

• Query API (Content::query() ≈ queryContent())
• Markdown parsing with frontmatter
• Heading extraction & TOC
• Navigation generation
• HMR support
• Vue components
• TypeScript support

⏳ Planned for v1.1:

• MDC (Markdown Components)
• Full-text search
• Syntax highlighting (Shiki)
• YAML/JSON file support

See Nuxt Content Comparison for detailed feature parity analysis.

Roadmap

• Markdown compilation
• Query API (Nuxt Content-compatible)
• Vue components
• HMR support
• TypeScript support
• MDC (Markdown Components) - v1.1
• Full-text search - v1.1
• Shiki syntax highlighting - v1.1
• YAML/JSON support - v1.1
• Content versioning - v1.2
• Multi-language support - v1.2

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

Security

If you discover any security-related issues, please email dev@farsi.dev instead of using the issue tracker.

See Security Policy for more details.

License

The MIT License (MIT). Please see License File for more information.

Credits

• Farsi Dev
• Inspired by Nuxt Content
• Built with Spatie's Laravel Package Skeleton
• All contributors

Package Architecture

This is a single Composer package that includes both PHP and JavaScript code.

📦 Installation: composer require farsi/inertia-content 📂 JavaScript: Included in vendor/farsi/inertia-content/resources/js/ 🔌 Vite Plugin: Import from vendor directory

See Package Structure and Architecture for details.

Support

• ⭐ Star the repo
• 🐛 Report bugs via GitHub Issues
• 💬 Discuss features via GitHub Discussions
• 📖 Read the full documentation