README

Magna Docs

The documentation plugin built for Laravel — live publishing, zero build step, zero Node.js.
Write, organise, and publish developer documentation directly inside your Magna CMS admin panel.

Public docs — light mode	Public docs — dark mode	Full-screen Markdown editor
Admin — Doc Pages list	Admin — Collections	Mobile responsive view

Why Magna Docs?

Most documentation platforms force you to maintain a completely separate website alongside your application.

Whether you use GitBook, VitePress, Docusaurus, MkDocs, or Docsify, you end up managing:

• a separate repository
• Node.js dependencies and build pipelines
• separate deployment workflows
• a synchronization problem between your app and its docs

Magna Docs takes a different approach. It lives inside your Laravel application as a native plugin. Every page is stored in your database, rendered with Blade, cached automatically, and live on the next page refresh the instant you hit Publish.

There is nothing extra to build, deploy, or maintain.

Built For

Magna Docs is the right tool for any team that wants documentation without a separate platform:

• 📚 Software & open-source project documentation
• 🔌 API references and developer portals
• 📖 Product manuals and user guides
• 🏢 Internal company wikis and SOPs
• 🎓 Training and onboarding documentation
• ❓ Customer help centres and knowledge bases
• 📒 SaaS platform documentation
• 📗 Installation guides and technical references

⭐ Key Features

• Full-screen distraction-free Markdown editor with toolbar
• Live publishing — edit, click Publish, refresh. Done.
• Collections and unlimited nested page hierarchy
• Automatic sidebar generation from your page tree
• Automatic Table of Contents from h2 / h3 headings
• Reading time estimation and "last updated" display
• Previous / Next page navigation
• Breadcrumb navigation with structured data
• Featured images from upload or media library
• Dark mode / light mode toggle (persists per session)
• Automatic SEO — Open Graph, Twitter Cards, JSON-LD, Sitemap
• REST API for headless or mobile consumption
• Multi-language / localization — per-page translations with locale switching
• Role-based editor permissions
• Shared Magna media library
• Custom domain, logo, favicon and site name
• Server-side rendering — no React, no Vue in the browser
• Automatic per-page HTML caching with instant invalidation
• Fully self-hosted, MIT licensed

Feature Comparison

Feature	Magna Docs	GitBook	Docusaurus	VitePress	MkDocs	BookStack
Self-hosted	✅	⚠️ paid	✅	✅	✅	✅
Laravel / PHP native	✅	❌	❌	❌	❌	❌
Filament admin integration	✅	❌	❌	❌	❌	❌
Live publishing (no rebuild)	✅	✅	❌	❌	❌	✅
Requires Node.js	❌	❌	✅	✅	❌	❌
Database-driven	✅	❌	❌	❌	❌	✅
Full-screen writing mode	✅	✅	❌	❌	❌	❌
Markdown support	✅	✅	✅	✅	✅	✅
JSON-LD structured data	✅	❌	⚠️	⚠️	❌	❌
Automatic XML sitemap	✅	⚠️	⚠️	⚠️	⚠️	❌
REST API	✅	✅	❌	❌	❌	❌
Role-based permissions	✅	✅ paid	❌	❌	❌	✅
Shared media library	✅	❌	❌	❌	❌	⚠️
Automatic breadcrumbs	✅	❌	⚠️	⚠️	⚠️	✅
Reading time	✅	❌	❌	❌	❌	❌
Prev / Next navigation	✅	✅	✅	✅	⚠️	✅
Multi-language translations	✅	✅ paid	⚠️	⚠️	⚠️	❌
Mobile responsive	✅	✅	✅	✅	✅	✅
Open source	✅	❌	✅	✅	✅	✅

Features

Full-Screen Markdown Editor

The editor takes over the entire screen — Filament chrome disappears, leaving nothing but your content.

• Rich toolbar: bold, italic, strikethrough, links, headings, lists, blockquotes, code blocks, tables, file attachments
• Dark / light mode toggle that persists between sessions
• Save Draft saves silently without redirecting; Publish / Update goes live immediately
• Slug auto-generated from the title while you type — override any time

Draft / Publish Workflow

• Every page starts as a draft — invisible to visitors until published
• Status badge in the sidebar: Draft / Published / Archived
• Publish date recorded automatically the moment a page goes live
• Topbar button switches to Update once a page is already published so you always know what you're doing

Collections & Nested Pages

• Collections group related pages (Getting Started, API Reference, etc.) — each has a title, slug, description, icon, colour, and sort order
• Nested pages — any page can be a child of another via parent_id, giving unlimited depth
• The public sidebar is built automatically from this tree; no manual menu editing ever

Auto Table of Contents

• Every h2 and h3 in the rendered page is extracted and displayed as a sticky anchor list in the right column
• All headings get permanent # permalink anchors via CommonMark's heading-permalink extension

SEO — Zero Config

Every published page ships with:

• Unique <title> and <meta name="description">
• Canonical URL
• Open Graph tags (og:title, og:description, og:image, og:url, og:type)
• Twitter Card metadata
• JSON-LD structured data: TechArticle + BreadcrumbList
• Auto-generated sitemap.xml at /docs/sitemap.xml with <lastmod> per page

No plugins, no config files, no SEO package needed.

Server-Rendered, No Build Step

The public frontend is pure Blade + CSS. Zero JavaScript frameworks are shipped to the browser.

• No npm run build after content changes
• Instant live pages — published content is visible on the next refresh
• Automatic HTML caching per page, keyed on page_id:updated_at, invalidated the moment a page is saved
• Excellent Core Web Vitals — fast FCP, fast LCP, no hydration delay

Frontend — Light & Dark Mode

Mobile

Fully responsive — the sidebar collapses on mobile, and the layout adapts to any screen width.

Additional Features

• Featured image — upload directly or pick from the Magna media library; toggle display per page
• Breadcrumb navigation — built automatically from the parent_id hierarchy
• Prev / Next navigation — cards at the bottom of each page, ordered by sidebar position
• Reading time — calculated from word count (~200 wpm), shown in the page footer
• Last updated — rendered from updated_at, always accurate
• Page feedback widget — "Was this page helpful? 👍 👎" stored locally, no third-party service

REST API

Every published page is available as JSON for headless or mobile consumption:

Endpoint	Description
GET /api/v1/docs/tree	Nested sidebar tree (collections → pages)
GET /api/v1/docs/pages	Flat list of all published pages
GET /api/v1/docs/pages/{slug}	Full content + breadcrumb for one page

Example response for /api/v1/docs/tree:

[
  {
    "title": "Getting Started",
    "slug": "getting-started",
    "children": [
      { "title": "Installation", "slug": "installation" },
      { "title": "Configuration", "slug": "configuration" }
    ]
  }
]

Useful for Next.js frontends, mobile apps, search indexing, and AI assistants.

Magna Docs vs GitBook

GitBook is one of the most popular documentation platforms today. It offers an excellent writing experience — but it is primarily a cloud-hosted SaaS product.

	Magna Docs	GitBook
Hosting	Self-hosted inside your app	Cloud SaaS (paid for teams)
Data ownership	Your database, your server	GitBook's servers
Authentication	Shared with your Laravel app	Separate GitBook account
Monthly cost	Free (open source)	Paid after free tier
Laravel integration	Native	None
Admin panel	Filament 5 inside your app	Separate GitBook UI
REST API	Built-in	Paid plans

If your application already runs on Laravel, Magna Docs eliminates the need to manage documentation on a separate platform with a separate login, separate billing, and separate deployment.

Magna Docs vs Docusaurus

Docusaurus is an excellent static site generator from Meta, widely used for open-source project documentation.

The fundamental difference: every documentation change in Docusaurus requires a rebuild and redeploy.

Docusaurus workflow:

1. Edit Markdown file
2. Commit to Git
3. Push to trigger CI
4. Build (npm run build) — takes minutes
5. Deploy to hosting
6. Wait for CDN propagation

Magna Docs workflow:

1. Edit page in admin
2. Click Publish
3. Refresh browser

No Node.js. No build. No deployment. No waiting.

	Magna Docs	Docusaurus
Requires Node.js	❌	✅
Build step on every edit	❌	✅
Deploy after edits	❌	✅
Live publishing	✅	❌
Edit inside admin panel	✅	❌
Database-backed content	✅	❌
Shared media library	✅	❌

Magna Docs vs VitePress

VitePress is lightweight and fast, but it still depends on Node.js and static site generation. Every content update requires running the build and redeploying.

Task	Magna Docs	VitePress
Requires Node.js	❌	✅
npm install on setup	❌	✅
Build after editing	❌	✅
Deploy after editing	❌	✅
Edit inside admin panel	✅	❌
Database storage	✅	❌
Role-based editor access	✅	❌
Shared app authentication	✅	❌

For Laravel teams already using Filament, Magna Docs provides a far more integrated experience — no separate toolchain, no separate user accounts, no separate deployment.

Magna Docs vs MkDocs

MkDocs is popular for Python projects and technical documentation. Like Docusaurus and VitePress, it generates static HTML at build time.

Magna Docs focuses on dynamic documentation management — editors update content without touching Git repositories or running build commands. The content team and the engineering team share one admin panel, one media library, and one permission system.

Magna Docs vs BookStack

BookStack is a solid self-hosted knowledge management platform. It serves a slightly different audience:

• BookStack is optimised for company-wide knowledge sharing, internal wikis, and team information
• Magna Docs is optimised for public-facing developer documentation — product docs, API references, installation guides, SaaS documentation

Magna Docs also integrates natively with Magna CMS and Filament, giving you a single admin panel for your entire application.

Architecture

Visitor Request
       │
       ▼
  Laravel Router
       │
       ▼
  DocsPageController
       │
       ├── Cache hit? ──→ Return cached HTML immediately
       │
       ▼
  DocPage model (Eloquent)
       │
       ▼
  CommonMark parser
       │
       ▼
  Blade templates
       │
       ▼
  Cache HTML (keyed on page_id:updated_at)
       │
       ▼
  Visitor receives fully rendered HTML

Unlike JavaScript documentation frameworks, there is no client-side rendering, no hydration, and no JavaScript framework shipped to the visitor.

Performance

• Server-side rendering — pages are Blade-rendered HTML; no React or Vue runtime in the browser
• Automatic per-page caching — rendered HTML cached immediately after first render
• Instant cache invalidation — only the updated page's cache is cleared when you save; no "clear all" button
• Lightweight frontend — Blade, CSS, and a small amount of vanilla JS only
• Fast Core Web Vitals — better FCP, better LCP, reduced JS execution, improved accessibility

Security

Magna Docs inherits Laravel's built-in security model:

• CSRF protection on all forms
• Authentication and authorization policies
• Role-based permissions (shared with the rest of the CMS)
• Request validation
• Escaped Blade templates (XSS-safe by default)
• Secure file uploads via Magna media library

No third-party authentication service required.

Installation

Coming soon — one-click install: Magna CMS will ship a built-in plugin marketplace where you can install Magna Docs with a single click from the admin panel — no terminal, no composer.json edits, no file copying. The steps below cover the v1.0 manual path.

Prerequisites

You need a running Magna CMS instance. Magna Docs is a plugin for Magna CMS — it is not a standalone application.

1. Add the plugin to your plugins directory

# From the root of your Magna CMS installation
git clone https://github.com/jish-44/Magna-Docs.git plugins-dev/magna/docs

Your directory structure should look like:

your-magna-cms/
├── app/
├── plugins-dev/
│   └── magna/
│       └── docs/          ← plugin lives here
│           ├── magna.json
│           ├── composer.json
│           └── src/
└── ...

2. Register the plugin path in your root composer.json

{
    "repositories": [
        { "type": "path", "url": "plugins-dev/magna/docs" }
    ]
}

3. Require the package

composer require magna/docs:@dev

4. Enable from the admin panel

Go to Admin → Plugins, find Magna Docs, and click Enable.

Enabling the plugin automatically runs database migrations and registers all routes, admin resources, and permissions. No php artisan migrate needed.

Usage

Creating your first page

1. In the admin sidebar, go to Magna Docs → Create Page
2. Type your title — the slug is auto-generated
3. Write content in Markdown using the full-screen editor
4. Optionally assign to a Collection and set a parent page for nesting
5. Click Publish page — it's live at /docs/{slug} immediately

Organising with Collections

1. Go to Magna Docs → Collections and create a collection (e.g. "Getting Started")
2. When editing a page, pick the collection in the Organisation sidebar panel
3. Pages are grouped by collection in the public sidebar, ordered by the order field

Setting up branding

Go to Magna Docs → Settings to set site name, logo, and favicon. These affect only the docs section and do not change anything else in your CMS.

Restricting editor access

In Magna Docs → Settings → Permissions, select which admin roles can create and edit pages. Leave empty to allow all admin roles.

Routes

Route	Description
GET /docs	Landing — redirects to the first published page
GET /docs/{slug}	Doc page with sidebar, TOC, breadcrumb, SEO meta
GET /docs/sitemap.xml	XML sitemap for all published pages
GET /api/v1/docs/tree	JSON — nested sidebar tree
GET /api/v1/docs/pages	JSON — flat list of published pages
GET /api/v1/docs/pages/{slug}	JSON — single page content + breadcrumb

Database Structure

doc_collections

Column	Type	Description
id	bigint	Primary key
title	string	Collection title
slug	string	URL slug
description	text	Short description
icon	string	Icon identifier
color	string	Sidebar accent colour
order	integer	Display order
is_public	boolean	Visibility

docs_pages

Column	Type	Description
id	bigint	Primary key
collection_id	bigint	Parent collection
parent_id	bigint	Parent page (nullable)
title	string	Page title
slug	string	URL slug
excerpt	text	Short summary
content	longtext	Markdown content
featured_image	string	Hero image path
show_featured_image	boolean	Show image on frontend
meta_title	string	SEO title override
meta_description	text	SEO description override
status	enum	draft / published / archived
order	integer	Sidebar order
is_published	boolean	Published flag
published_at	timestamp	Publish date

Requirements

Requirement	Version
PHP	8.3 or higher
Laravel	13.x
Magna CMS	Latest
Filament	5.x
Composer	Latest

Frequently Asked Questions

Does Magna Docs require Node.js? No. Everything runs inside Laravel. There is no npm, no Vite, and no build step.

Does it generate static HTML? No. Pages are rendered dynamically by Blade on every request (or served from cache). Publishing is instant — no rebuild, no deployment.

Does it support Markdown? Yes. Markdown is parsed by league/commonmark — a full CommonMark implementation with extensions.

Can I use it for API documentation? Absolutely. Magna Docs is ideal for REST API references, SDK docs, and developer portals.

Can I use it as a knowledge base or internal wiki? Yes. Collections and nested pages make it easy to structure any type of documentation project.

Is it SEO friendly? Yes. Every page automatically gets meta tags, Open Graph, Twitter Cards, JSON-LD structured data, canonical URLs, and a sitemap.

Does it support multiple languages? Yes. Magna Docs ships with a built-in translation system — each page can have a translated title and content per locale, stored in a dedicated docs_page_translations table. Switch locale to serve documentation in any language.

Can I serve docs on my own domain (e.g. docs.myapp.com)? Yes. Configure a custom domain in Magna Docs → Settings.

Can I restrict who edits documentation? Yes. Assign editor access to specific Magna CMS admin roles in the settings.

Do I need to run php artisan migrate manually? No. Migrations run automatically when you enable the plugin from the admin panel.

Is Magna Docs open source? Yes. Released under the MIT License.

Roadmap

Planned for future releases:

• Global full-text search (Algolia DocSearch / built-in)
• Versioned documentation (e.g. v1, v2)
• Import from GitHub Markdown files
• Export to PDF
• Export to ZIP / static HTML
• Page revision history
• Scheduled publishing
• Comments on pages
• Page analytics
• Custom themes
• Documentation templates
• AI writing assistant integration
• One-click install via Magna CMS plugin marketplace

Contributing

Contributions are welcome. You can help by:

• Reporting bugs with clear reproduction steps
• Suggesting features via GitHub Issues
• Submitting pull requests (please follow the existing code style)
• Improving documentation

Please include your PHP version, Laravel version, Magna CMS version, and plugin version in any bug report.

License

Magna Docs is open-source software released under the MIT License — see LICENSE for full details.

Made with ❤️ for the Laravel & Magna CMS community.
If Magna Docs saves you from maintaining a separate documentation platform, consider giving the repo a ⭐