Download the PHP package bristol-digital/qwikblog without Composer

QwikBlog

A simple, file-based blog for Laravel — headless front-end + lightweight admin with a Livewire-powered image gallery and a WYSIWYG body editor. No database required. Posts live in resources/posts/ as Markdown files with YAML front matter.

Installation

The package's service provider auto-registers via Laravel's package discovery. Then publish the config and the admin's JS entry point:

The admin JS publish puts resources/js/qwikblog-admin.js in your host app — a tiny Vite entry that imports Toast UI Editor for the post form's body field. Wire it into your Vite build (vite.config.js):

Install the npm dependency that the admin JS imports:

Note: the package can't auto-install its own npm dependencies because Composer and npm are separate ecosystems. Every Laravel package that uses JS libraries works this way — composer require for PHP, npm install for JS, no automatic bridge between them.

Set admin credentials in .env (see Configuration):

Make sure your host app's Tailwind setup includes the package's blade files in its content scanning (so admin styling Just Works) and has the typography plugin and Alpine for the public views. In resources/css/app.css (or your Tailwind config):

In resources/js/app.js:

The package's public views (post index, single post, etc.) extend a layout in your host app. Which value of QWIKBLOG_LAYOUT to set in .env depends on what your project has:

• If you have resources/views/app.blade.php — QWIKBLOG_LAYOUT=app
• If you have resources/views/layouts/app.blade.php — QWIKBLOG_LAYOUT=layouts.app

• If you have neither yet (common on fresh Laravel 11+ installs) — publish the package's bundled starter layout and point at it:

  Then in .env:

  The bundled starter is clean and functional; you can edit it (resources/views/vendor/qwikblog/app.blade.php) or replace it later with your own layout.

Whichever layout you use, make sure it has @stack('head') inside <head> so the package can inject SEO meta. To enable RSS autodiscovery, also add:

Finally:

To populate with the bundled flamenco demo content (12 posts across 4 categories with images):

Visit / to see the blog. Visit /admin to log in.

Routes

Public views live at resources/views/blog/index.blade.php and show.blade.php. Both extend the host site's app.blade.php layout. The package ships a starter app.blade.php; host sites typically have their own and only need @stack('head') somewhere in <head> for SEO meta to inject correctly.

Post fields

Posts are stored as resources/posts/YYYY-MM-DD-slug.md. Front matter:

The admin writes this format automatically. The legacy singular category: field is still read for back-compat with older posts.

List values — inline or multi-line. Categories and tags can be written either inline (as above) or as multi-line YAML lists; both parse identically:

The admin always writes the inline form. The multi-line form is supported for hand-authored or pasted-in content — useful when working with AI-generated drafts or copying from snippets that use standard YAML list syntax.

Categories and tags

Posts can have any number of each. Both render in the right-rail sidebar on the index page (categories as a vertical list, tags inline as #hashtag chips), each with a post count. Active filter is highlighted.

One filter at a time — clicking a different chip replaces the active filter rather than stacking with AND. Each post's own categories and tags also appear in the show-page sidebar with counts.

If no published post has any categories, the categories section hides entirely. Same for tags. The view checks count(...) > 0 before rendering.

URL collision

Posts win on slug collision. A post titled "Palos" would shadow the Palos category filter at /blog/palos. If you need strict separation, set QWIKBLOG_TAXONOMY_URL_STYLE=prefixed — chip links then go to /blog/category/palos etc. and never collide with post slugs.

Scheduling

Set date to a future timestamp. The post will:

• Show in the admin index with a yellow Scheduled badge and a relative countdown ("in 3 weeks") that updates on the 30-second wire:poll
• Be hidden from the public /blog until the date passes
• Return 404 at its slug to public visitors but render normally for logged-in admins (preview)
• Auto-publish silently when the date arrives — no cron job required

Search

/blog/search?q=... runs an AND match across title, subtitle, summary, author, categories, tags, and rendered body content. Multi-term queries are supported (jerez bulerías returns posts containing both terms). Pure-PHP str_contains — fine up to a few thousand posts; past that, swap in a real index.

Search results pages are noindex by default — every unique query is a unique URL and not worth indexing.

Author pages

/blog/author/{slug} lists every published post by an author. The author byline on each show page links here automatically.

Archive

/blog/{year} and /blog/{year}/{month} return posts from that period. The sidebar archive nav appears when at least 2 distinct months are represented; below that it stays hidden (a single-month archive is just the index).

Related posts

Each post page shows up to 3 related posts at the bottom, scored by taxonomy overlap:

Posts scoring 0 are excluded entirely — better to hide the section than show weak recommendations. Weights and limit are configurable.

RSS, sitemap, SEO

Reference the sitemap from public/robots.txt:

Image gallery

Each post has its own folder at public/images/blog/{slug}/. Images are numbered 1.jpg, 2.jpg, … and ordering is set by the numeric filename.

The Livewire gallery (/admin/posts/{slug}/images) lets you:

• Drag-and-drop upload (multi-select, JPG/PNG/GIF, max 20 MB each)
• Resize and re-orient automatically (max 1600×1200, 85% quality JPG; GIFs pass through untouched so animations are preserved)
• Reorder images by drag
• Delete individual images
• Copy a path to the clipboard for pasting into the post's hero_image field

If hero_image is left blank in the front matter, the first numerically- named image is used automatically. Set it explicitly to override.

When a post is renamed, its image folder moves with it. When a post is deleted, its image folder is deleted too.

On the public show page, multiple images render as a crossfading carousel with prev/next, dot navigation, a counter, and a thumbnail strip.

Body editor (WYSIWYG)

The admin's body field uses Toast UI Editor, defaulting to WYSIWYG mode with a Markdown toggle in the toolbar. The editor is bundled via Vite from resources/js/qwikblog-admin.js (published into your host app on install — see Installation) — no CDN dependency at runtime. Posts are stored as plain CommonMark, so files remain hand-editable.

If you don't run the editor and just want plain markdown editing, delete resources/js/qwikblog-admin.js and remove @vite(['resources/js/qwikblog-admin.js']) from the admin layout (publish the views via vendor:publish --tag=qwikblog-views to override). The textarea behind the editor stays usable as a markdown fallback in any case.

Admin

A small admin lives at /admin (or whatever path you set via QWIKBLOG_ADMIN_PATH).

Auth — three options

The package's admin protection is configurable via QWIKBLOG_ADMIN_MIDDLEWARE. By default it uses the package's own self-contained auth (single shared username/password from .env). For sites with their own auth system, you can wire the blog admin into that instead so users only log in once.

Option 1 — Self-contained auth (default)

Set credentials in .env:

If either is empty, login is refused — there is no default password. Visit /admin/login to log in. This is the right choice for static sites, no-database deployments, or any host that doesn't already have a login system.

Option 2 — Integrate with Laravel's auth

If your host app already has Laravel auth set up (Breeze, Jetstream, Fortify, Sanctum, or a starter kit's bundled login), tell the package to use that instead:

Now any user logged in to your host app can access the blog admin at /admin (or QWIKBLOG_ADMIN_PATH). The logout button in the admin chrome calls your host's logout endpoint. You can ignore ADMIN_USERNAME / ADMIN_PASSWORD entirely.

To restrict the blog admin to specific users (not just any authenticated user), combine with a Laravel gate:

Then define the gate in your host app's AppServiceProvider:

Option 3 — Custom middleware

Any middleware alias your host registers will work. Examples:

Routes

The package's AdminAuth middleware (alias admin) uses session auth, file-based by default (SESSION_DRIVER=file), so no database is required.

Filtering

The admin posts index has four filters that combine with AND:

Filter state is preserved in the URL — /admin/posts?status=scheduled&category=Palos is bookmarkable and reload-safe. The header shows totals (12 published · 3 scheduled · 15 total); the Status dropdown shows the same counts inline so editors can find scheduled posts without first applying a filter.

Page paginates at 30 by default — useful when scheduling content months ahead. Override via QWIKBLOG_ADMIN_PER_PAGE.

Scheduled rows show their relative publish time underneath the date ("in 3 weeks"), updating on the 30-second wire:poll.

Bulk import

For migrating content or seeding test data:

The manifest is a .php file returning an array (recommended for long bodies — heredoc is friendlier than JSON-escaping) or .json.

Image URLs (when present) are downloaded into public/images/blog/{slug}/ at import time. Failures are non-fatal — posts are still created.

Example post sets

The package ships a sample manifest (12 demo flamenco posts across 4 categories, with images) you can use to populate a fresh install:

The command reads the bundled manifest directly from the package and downloads the referenced images. You only need to publish the seeds (vendor:publish --tag=qwikblog-seeds) if you want to edit the manifest before importing.

To remove the demo content later:

Customising the look

To customise any of the package's public-facing views (post index, single post, RSS feed, sitemap), publish them into your host app:

This copies every Blade file from the package into resources/views/vendor/qwikblog/ in your project. The package's own copies stay untouched; Laravel's view loader gives priority to whatever sits in resources/views/vendor/qwikblog/, so anything you edit there overrides the default.

The two views you'll most likely want to customise:

Both extend the layout named by QWIKBLOG_LAYOUT (default app). Article body styling uses the Tailwind Typography plugin — the prose class on <article> is the source of truth.

To revert to the package defaults later, just delete the file from resources/views/vendor/qwikblog/ — the package's own version takes over again automatically.

The admin views can be customised the same way (they're published by the same command), but most sites won't need to — the admin is meant to be functional rather than branded.

Configuration

All package configuration lives in config/qwikblog.php and reads from .env overrides. Every value is optional except admin credentials.

After editing .env:

Clears config, route, view and compiled caches in one go. Required if you've previously run php artisan config:cache or are deployed in a way that caches config.

To verify a value is being read:

If the value comes back as the default when you've set the env var, either config/qwikblog.php isn't at the project root, the env var is mistyped (case-sensitive), or config is still cached.

Cache

Posts are cached for an hour. To clear manually:

The admin clears this cache automatically on every create/update/delete, and blog:import clears it after a bulk import.

Common commands

Troubleshooting

Architecture

Dependencies

PHP / Composer:

• laravel/framework ^12
• livewire/livewire ^3.7

Node / npm:

• @toast-ui/editor — admin body editor (Vite-bundled)
• @tailwindcss/typography — prose styling on the show page
• alpinejs — public-facing carousel
• tailwindcss ^4 with @tailwindcss/vite

Node / npm (in your host app):

• @toast-ui/editor — admin body editor (Vite-bundled via the published qwikblog-admin.js)
• @tailwindcss/typography — prose styling on the show page
• alpinejs — public-facing carousel
• tailwindcss ^4 with @tailwindcss/vite

CDN-loaded by the admin chrome only:

• Tailwind (Play CDN)
• Sortable.js (gallery reordering)

Alpine in the admin is provided by Livewire's bundled copy — do not load it separately.