Getting Started

Installation:

composer require ojessecruz/simple-blog
php artisan vendor:publish --tag="simple-blog-migrations"
php artisan vendor:publish --tag="simple-blog-config"
php artisan migrate

Focus on config/blog.php first—this is the central hub for all customization.

First Use Case:
- Protect admin routes by configuring admin_middleware in config/blog.php (e.g., ['web', 'auth', 'can:manage-blog']).
- Link your User model to the Author contract by implementing getBlogAuthorName() and getBlogAuthorInitials().
- Test the public blog at /blog and admin panel at /admin/blog.
Quick Wins:
- Publish the views (--tag="simple-blog-views") if you need to tweak the default UI (e.g., swap Tailwind colors).
- Use the Post and PostCategory models to query content directly (e.g., for sitemaps or exports).

Implementation Patterns

1. Workflow: Content Creation

Admin Panel:
- Use the Livewire-powered CRUD at /admin/blog to create/edit posts.
- Drafts: Toggle the "Mark as draft" checkbox to hide unpublished posts from /blog.
- Preview: Click the "Preview" button to open a new tab with a live Markdown render (uses Str::markdown()).
- Split View: Toggle between Markdown-only editing and a side-by-side editor/preview (added in v0.4.0).
Public Side:
- Posts render with automatic SEO meta tags (via @stack('head') in your layout).
- Categories are auto-linked (e.g., /blog/category/{slug}).

2. Integration with Existing Auth

Middleware Flexibility:
- Configure admin_middleware in config/blog.php to reuse your app’s auth logic (e.g., ['web', 'auth:admin'] or a custom Gate).
- Example Gate in AuthServiceProvider:
```
Gate::define('manage-blog', fn ($user) => $user->is_admin);
```
Public Access:
- Set public_middleware to control who can view the blog (e.g., ['web'] for open access or ['web', 'auth'] for logged-in users only).

3. Layout Customization

Public Layout:
- Extend the default blog::layouts.public by publishing views and overriding resources/views/vendor/blog/layouts/public.blade.php.
- Critical: Ensure your layout includes @stack('head') for SEO tags.
- Example: Wrap the blog in your app’s header/footer:
```
<x-app-layout>
    @yield('content')
</x-app-layout>
```
```
// config/blog.php
'layouts.public' => 'layouts.blog-public',
```
Admin Layout:
- Point layouts.admin to your admin shell (e.g., layouts.app for Jetstream/Breeze):
```
'layouts.admin' => 'layouts.app',
```

4. Extending Functionality

CTA Injection:
- Add a call-to-action (e.g., newsletter signup) by creating a Blade view (e.g., resources/views/components/blog-cta.blade.php) and configuring:
```
'cta_view' => 'components.blog-cta',
```
- The view receives the $post model.

Custom Queries:

Use the Post model for custom logic:

use Jessecruz\SimpleBlog\Models\Post;

$featuredPosts = Post::published()->latest()->take(3)->get();

Dark Mode:
- Leverage Tailwind’s dark: classes (supported since v0.4.0). Ensure your tailwind.config.js includes:
```
content: [
    './vendor/ojessecruz/simple-blog/resources/views/**/*.blade.php',
],
```

5. Routing

Prefixes:

Customize route prefixes in config/blog.php:

'route_prefix' => 'journal',          // /journal instead of /blog
'admin_route_prefix' => 'content',   // /content/blog

Named Routes:
- Use Laravel’s route helpers (e.g., route('blog.show', $post)) for links.

Gotchas and Tips

Pitfalls

SEO Meta Tags Missing:
- Symptom: Post titles/meta tags don’t appear in <head>.
- Fix: Ensure your public layout includes @stack('head').
- Debug: Check if the package’s @push('head') directives are rendering.
Dark Mode Flickering:
- Symptom: Admin form controls appear black-on-dark or white-on-light.
- Fix: Update to v0.4.1+ (patches dark mode styles for inputs/buttons). If using a custom theme, manually add:
```
<input class="bg-white dark:bg-zinc-900 text-zinc-900 dark:text-zinc-100">
```
Tailwind Classes Not Compiled:
- Symptom: Customized views show [object Object] or broken styles.
- Fix: Add the package’s views to tailwind.config.js:
```
content: [
    './vendor/ojessecruz/simple-blog/resources/views/**/*.blade.php',
],
```
Drafts Still Visible:
- Symptom: Draft posts appear on /blog.
- Fix: Ensure published_at is null for drafts and query Post::published() (not Post::all()).
Livewire Scripts Duplication:
- Symptom: @livewireScripts appears twice in admin views.
- Fix: Set 'assets' => [] in config/blog.php if your layout already loads Livewire scripts.

Debugging Tips

Livewire Errors:
- Check the browser console for Livewire JS errors (e.g., missing wire:model bindings).
- Clear Livewire cache:
```
php artisan livewire:discover
```
Markdown Parsing:
- Test raw Markdown in the admin preview to ensure Str::markdown() behaves as expected. Example:
```
# Test
**Bold** and [links](https://example.com).
```
Route Conflicts:
- Use php artisan route:list to verify no conflicts exist with your app’s routes.

Extension Points

Custom Post Fields:

Extend the Post model by adding traits or relationships:

// app/Models/Post.php
use Jessecruz\SimpleBlog\Models\Post as BasePost;

class Post extends BasePost {
    public function tags() {
        return $this->morphToMany(Tag::class, 'taggable');
    }
}

Override Markdown Processing:

Extend the Str::markdown() pipeline in config/blog.php:

'markdown' => [
    'tables' => true, // Enable GitHub-style tables
    'html' => false,   // Escape HTML by default
],

For advanced use, bind a custom Markdown renderer to the container:

$this->app->bind(\Jessecruz\SimpleBlog\Contracts\MarkdownRenderer::class, function () {
    return new CustomMarkdownRenderer();
});

Custom Validation:
- Extend the Livewire form rules by publishing the admin views and modifying: resources/views/vendor/blog/admin/post-form.blade.php.
- Add validation logic in a custom Livewire component extending PostForm.
Localization:
- Publish translations:
```
php artisan vendor:publish --tag="simple-blog-lang"
```
- Override strings in resources/lang/en/blog.php (or your locale).

Sitemap Integration:

Use the Post model to generate a sitemap:

$posts = Post::published()->latest('published_at')->get();
Sitemap::add($posts, function ($post) {
    return route('blog.show', $post);
});

Performance Quirks

N+1 Queries:
- Eager-load relationships when querying posts:
```
Post::with('category', 'author')->published()->get();
```
Livewire Memory Leaks:
- Avoid storing large data in Livewire properties. Use public properties for simple data and protected for complex logic.

Tailwind-Specific Tips

Class Conflicts:
- If your app uses Tailwind, ensure the package’s classes don’t clash. Example: Prefix package-specific classes:

Simple Blog Laravel Package