Ampersand
Plug-and-play flat file markdown blog tool for your Laravel-project. Create an article or blog-section on your site without the hassle of setting up tables, models or your own flat file-system.
Built upon spatie/sheets to handle the markdown-files and YAML-front matter parsing.
Note: This package is built for quick and easy setup and use – don't expect a fully featured CMS.
🛠
Install and configure
Require package:
$ composer require olssonm/ampersand
Publish config-files and views:
$ php artisan vendor:publish --provider="Olssonm\Ampersand\AmpersandServiceProvider"
In config/ampersand.php you can now customize the settings to your liking. Views are available at resources/views/vendor/ampersand
✏️
Writing posts
Filename format
All posts should be stores in your posts_path-directory with the filename format of 2021-03-30.my-post.md, i.e. {date:Y-m-d}.{slug}.md.
The slug is what determins at what URL your post will be available at.
Artisan command
You can quickly create a new post via the artisan command:
php artisan ampersand:new
YAML front matter
Posts can contain any number of attributes via YAML-front matter:
---
title: This is a new post
date: '2020-01-01 20:00:01'
cover: https://amazingimages.com/my-cover.jpg
---
My post in **Markdown**
🖥
Displaying posts
Two views are shipped with this package; an index-view and a show-view (used for single posts). They are located in /resources/vendor/views/ampersand after installation and are fully customizable.
In index.blade.php a collection of post-objects is available via the $posts-variable. It behaves much as a standard Eloquent-collection.
@foreach ($posts as $post)
<h2>{{ $post->title }}</h2>
<div>
{!! $post->contents !!}
</div>
@endforeach
Pagination-links are also available:
{{ $posts->links() }}
The Post-object contains all your front matter attributes as well as slug, date and contents.
{{ $post->slug }} // my-post
{{ $post->date->format('Y-m-d') }} // 2021-03-30
{{ $post->contents }} // <p>My post in <strong>markdown</strong></p>
{{ $post->cover }} // https://amazingimages.com/my-cover.jpg
Retrieve posts in your application
You can retrieve posts and filter them as a collection anywhere in your application using the Post-model:
use Olssonm\Ampersand\Models\Post;
// Reject posts where is_draft is true or has a date in the future
$posts = Post::all()->reject(function($item) {
return $item->is_draft || $post->date->lessThan(now());
});
The posts are sorted by descending date per default, so to get the latest post:
// Get first post
$post = Post::all()->first();
🚦
Routes
The package routes are ampersand.index and ampersand.show:
{{ route('ampersand.index') }} // http://mysite.test/blog
@foreach ($posts as $post)
// The show-route accepts either a Olssonm\Ampersand\Models\Post-object
// or a string; the post's slug
{{ route('ampersand.show', $post) }} // http://mysite.test/blog/post-slug
{{ route('ampersand.show', 'post-slug') }} // http://mysite.test/blog/post-slug
@endforeach
Defining your own routes
The default routes are registered with the ampersand-name and the default web-middleware group.
If you by any reason want to override this (for example if you want to have your articles behind a login or maybe you don't use the standard web-middleware group), you may set register_routes to false in ampersand.php, and then register them yourself:
// /routes/web.php
use Olssonm\Ampersand\Http\Controllers\PostController;
Route::group(['middleware' => 'can:read', function() {
Route::get('/articles', [PostController::class, 'index'])->name('article.index');
Route::get('/articles/{post}', [PostController::class, 'show'])->name('article.show');
}]);
// A link to the blog index in some view
{{ route('article.index') }} // http://mysite.test/articles
License
The MIT License (MIT). Please see the LICENSE.md for more information.
© 2021 Marcus Olsson.
1.2k Dec 31, 2022
358 Nov 26, 2022
22 Dec 14, 2022
801 Dec 28, 2022
1.7k Jan 3, 2023
10 Oct 23, 2021
![Plug & Play [CURL + Composer Optional], Proxy as a Service, Multi-tenant, Multi-Threaded, with Cache & Article Spinner](https://github.com/4dboard/proxy-yxorp/raw/main/asset/logo.png){kind=logo}
12 Nov 17, 2022
3.3k Jan 1, 2023
13.6k Dec 24, 2022
4 Oct 28, 2022
858 Jan 6, 2023
31.1k Jan 8, 2023
279 Dec 28, 2022
19 Jul 5, 2021
131 Dec 16, 2022
43 Nov 28, 2022
56 Nov 26, 2022
2.4k Jan 1, 2023
14.3k Jan 8, 2023
989 Dec 16, 2022
357 Jan 3, 2023
2 Dec 3, 2021
5 May 29, 2022
1 Jan 18, 2022
5 Dec 9, 2022