Code Monkey home page Code Monkey logo

ampersand's Introduction

Ampersand โ€“ Blogging for Laravel

Ampersand

Latest Version on Packagist Build Status Software License

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

See it in action

Sites in the wild that uses Ampersand

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 for more information.

ยฉ 2021 Marcus Olsson.

ampersand's People

Contributors

olssonm avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar

ampersand's Issues

Html syntax not rendering

Hi, first of all, thank you for your work :)

I have a doubt: markdown by default supports html syntax but when I put some html code in a .md blog post file, it doesn't render.

Am I missing something or it's the package expected behavior?

Thanks so much, best regards.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.