ampersand

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #llm #go #android #windows #awesome #cli #pytorch #openai #ios #open-source

(★ 27)

Plug and play flat file markdown blog for your Laravel-projects

ampersand Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Ampersand

[![Latest Version on Packagist](https://img.shields.io/packagist/v/olssonm/ampersand.svg?style=flat-square)](https://packagist.org/packages/olssonm/ampersand)
[![Build Status](https://img.shields.io/github/actions/workflow/status/olssonm/ampersand/test.yml?branch=main&style=flat-square&label=tests)](https://github.com/olssonm/ampersand/actions?query=workflow%3A%22Run+tests%22)
[![Software License](https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://raw.githubusercontent.com/olssonm/ampersand/main/LICENSE.md)

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](https://github.com/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 determines 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.

``` php
@foreach ($posts as $post)
    <h2>{{ $post->title }}</h2>
    <div>
        {!! $post->contents !!}
    </div>
@endforeach
```

Pagination-links are also available:

``` php
{{ $posts->links() }}
```

The Post-object contains all your front matter attributes as well as `slug`, `date` and `contents`.

``` php
{{ $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:

``` php
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:

``` php
// Get first post
$post = Post::all()->first();
```

### 🚦 Routes

The package routes are `ampersand.index` and `ampersand.show`:

```php
{{ 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:

``` php
// /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
```

### See it in action

Sites in the wild that uses Ampersand

[esignering.se/blogg](https://esignering.se/blogg)

*Do you use Ampersand and want your site featured here? Submit a PR!*

### License

The MIT License (MIT). Please see the [LICENSE.md](LICENSE.md) for more information.

ampersand

ampersand Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

ampersand

ampersand Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README