Getting Started

Minimal Steps to First Use

Installation

composer require bristol-digital/qwikblog
php artisan vendor:publish --tag=qwikblog-config
php artisan vendor:publish --tag=qwikblog-admin-js
npm install @toast-ui/editor

Configure .env

ADMIN_USERNAME=admin
ADMIN_PASSWORD=securepassword
QWIKBLOG_LAYOUT=app  # or your custom layout path

Update vite.config.js

input: [
  'resources/js/app.js',
  'resources/js/qwikblog-admin.js',  // Add this line
],

Ensure Tailwind setup Add @source directive in app.css:

@source "../../vendor/bristol-digital/qwikblog/resources/views/**/*.blade.php";

Run migrations (if using custom auth)
```
php artisan migrate
```

Seed demo content (optional)

php artisan vendor:publish --tag=qwikblog-seeds
php artisan blog:examples flamenco

Start dev server
```
npm run dev
php artisan serve
```

First Use Case: Create a Blog Post

Visit /admin and log in with your .env credentials.
Click "New Post" to open the editor.
Fill in the YAML front matter (title, summary, categories, etc.).
Write your post in Markdown or use the WYSIWYG editor.
Upload images via the "Images" tab (drag-and-drop or manual upload).
Save and publish. Your post will appear at /blog/{slug}.

Implementation Patterns

1. Post Workflow

Drafting: Use the WYSIWYG editor for rich content or Markdown for simplicity.
Scheduling: Set a future date in front matter to schedule posts (auto-publishes when due).
Images: Upload via the Livewire gallery. Paths auto-populate into hero_image or body markdown.
Preview: Public visitors see a 404 for scheduled posts, but admins can preview via /blog/{slug}.

2. Admin Integration

Auth Integration:
- Self-contained: Use ADMIN_USERNAME/ADMIN_PASSWORD (default).
- Laravel Auth: Set QWIKBLOG_ADMIN_MIDDLEWARE=auth to reuse your existing auth system.
- Custom Middleware: Stack middleware like auth,can:manage-blog for role-based access.
Livewire Components:
- The admin uses Livewire for dynamic filtering (search, categories, tags, status).
- Polls every 30s to update scheduled post countdowns.
- Example: Filter for scheduled posts via /admin/posts?status=scheduled.

3. Frontend Customization

Layouts: Extend the package’s views (blog/index.blade.php, blog/show.blade.php) with your own layout.
SEO: Ensure @stack('head') exists in your layout for dynamic meta tags (OG, Twitter Cards, canonical URLs).
Styling: Override Tailwind classes in your CSS. The package uses utility classes for consistency.
Routes: All public routes are prefixed with /blog by default. Customize via QWIKBLOG_ROUTE_PREFIX.

4. Content Management

File Structure:
- Posts: resources/posts/YYYY-MM-DD-slug.md
- Images: public/images/blog/{slug}/1.jpg, 2.jpg, etc.
Front Matter: Use YAML for metadata (title, categories, tags, etc.). Supports both inline and multi-line YAML.
Taxonomies:
- Categories/tags appear in the sidebar. Clicking a category/tag filters posts (e.g., /blog/category/palos).
- Avoid slug collisions by setting QWIKBLOG_TAXONOMY_URL_STYLE=prefixed.

5. Extending Functionality

Custom Fields: Add fields to front matter by extending the Post model or using Laravel’s file caching.
Search: Replace str_contains with Algolia/Meilisearch for large post volumes.
RSS/Sitemap: Extend the XML generators in app/Providers/QwikBlogServiceProvider.php.
Image Processing: Hook into the ImageUploader service to add custom logic (e.g., watermarking).

6. Deployment

No Database: Ideal for static sites or headless CMS setups.
File Permissions: Ensure resources/posts/ and public/images/blog/ are writable by the web server.
Caching: Clear Laravel’s file cache (php artisan cache:clear) after adding new posts or layouts.

Gotchas and Tips

Pitfalls

Missing @stack('head'):
- Issue: SEO meta (OG tags, canonical URLs) won’t render.
- Fix: Add @stack('head') to your layout’s <head> section.
Admin JS Not Loading:
- Issue: qwikblog-admin.js fails to compile or isn’t included in Vite.
- Fix:
  - Ensure resources/js/qwikblog-admin.js exists (published via vendor:publish).
  - Add it to vite.config.js under input.
  - Run npm install @toast-ui/editor.
Image Paths Broken:
- Issue: Uploaded images don’t appear or 404.
- Fix:
  - Verify hero_image paths start with / (e.g., /images/blog/post-slug/1.jpg).
  - Check public/images/blog/{slug}/ permissions.
  - Clear Laravel’s file cache if paths were recently updated.
Scheduled Posts Not Auto-Publishing:
- Issue: Posts remain hidden after their scheduled date.
- Fix:
  - Ensure date in front matter is in YYYY-MM-DD HH:MM:SS format.
  - Check Laravel’s queue worker isn’t blocked (though QwikBlog uses no queue; it’s file-based).
Slug Collisions:
- Issue: A post titled "Palos" hides the /blog/palos category filter.
- Fix: Set QWIKBLOG_TAXONOMY_URL_STYLE=prefixed in .env to force /blog/category/palos.
Tailwind Styles Not Applying:
- Issue: Admin or public views look unstyled.
- Fix:
  - Ensure @source in app.css includes the package’s views.
  - Rebuild Tailwind (npm run dev or npm run build).
Multi-Line YAML Parsing:
- Issue: Categories/tags with multi-line YAML fail to parse.
- Fix: Use inline YAML (e.g., categories: Announcements, News) or manually convert to the expected format.
Alpine.js Conflicts:
- Issue: Alpine directives (e.g., x-data) stop working in public views.
- Fix: Ensure Alpine.start() is called in app.js after the package’s JS loads.

Debugging Tips

Check File Permissions:
```
ls -la resources/posts/ public/images/blog/
```
Ensure the web server user (e.g., www-data) can write to these directories.
Verify Front Matter: Use a YAML linter (e.g., YAML Lint) to validate post files.
Inspect Livewire Polling: Scheduled post countdowns rely on Livewire’s wire:poll. Check browser dev tools (Network tab) for 30-second requests to /admin/posts.

Clear Caches:

php artisan cache:clear
php artisan view:clear
php artisan config:clear

Log Admin Actions: Add debug logs in app/Providers/QwikBlogServiceProvider.php to trace post creation/updates.

Configuration Quirks

QWIKBLOG_LAYOUT:
- If using a custom layout, ensure it extends the package’s starter layout or replicates its @stack('head') and other requirements.
- Example: QWIKBLOG_LAYOUT=layouts.app (for resources/views/layouts/app.blade.php).
QWIKBLOG_TAXONOMY_URL_STYLE:
- Set to prefixed to avoid slug collisions (e.g., /blog/category/palos instead of /blog/palos).
- Default: flat (no prefix).
QWIKBLOG_ADMIN_MIDDLEWARE:
- Use auth to integrate with Laravel’s auth, but ensure your users have the correct permissions.
- For role-based access, combine with gates (e.g.,

Qwikblog Laravel Package

Getting Started

Minimal Steps to First Use

First Use Case: Create a Blog Post

Implementation Patterns

1. Post Workflow

2. Admin Integration

3. Frontend Customization

4. Content Management

5. Extending Functionality

6. Deployment

Gotchas and Tips

Pitfalls

Debugging Tips

Configuration Quirks