Downloads
Stars
Version
Fusion is a Laravel package designed to manage Markdown content via Eloquent Models, eliminating the necessity for a conventional database setup. It achieves this by leveraging Markdown files enhanced with Frontmatter.
Fusion aids in website development by integrating the power of Markdown and Frontmatter, enabling developers to create content-driven Web sites without having to manage databases.
With Fusion, developers can leverage the simplicity of Markdown syntax combined with the flexibility of Frontmatter to seamlessly organize and structure content.
By parsing Frontmatter into Eloquent models, Fusion enables developers to create complex, structured websites with ease. Say goodbye to the complexities of database management and welcome simplified website development with Fusion.
[!WARNING] The package is under development (version 0.0.x), so the functions, classes and methods provided can be changed, especially for the
FusionBaseModel
model class. So, if you want to start using the package in order to provide feedback, you are welcome, but please don't use it in production until the version 1.0.0 will be released. Thank you
You can install the package via the composer
tool:
composer require hi-folks/fusion
Once you installed Fusion you can start the process of creating content in Markdown files and querying the files through the Models. For example, now we are going to create articles in Markdown format and we will parse and query them like you can do it with a database.
In the resources/content
directory, you can create the article
directory.
In the resources/content/article
, you can create your Markdown files with a frontmatter header like for example:
---
date: 2024-04-05
title: Example title for article 1
excerpt: This will be a short excerpt from article number 1.
published: true
---
# Article 1
Markdown goes here
you can name this file as resources/content/article/article-1.md
You can create similarly the other Markdown files. These files represent your articles.
Similarly, you are doing with a database, you can create your model for loading the markdown files.
Because you are creating articles you can create your model as app/Models/Article.php
.
You can fill the file in this way:
<?php
namespace App\Models;
use HiFolks\Fusion\Models\FusionBaseModel;
use HiFolks\Fusion\Traits\FusionModelTrait;
class Article extends FusionBaseModel
{
use FusionModelTrait;
public function frontmatterFields(): array
{
return [
"excerpt"
];
}
}
Consider that:
extends FusionBaseModel
;use FusionModelTrait;
frontmatterFields()
function for returning the list of the field names used in the frontmatter header.If you want to create automatically the Model file, based on the structure and the content of the Markdown files you can use the fusion:sync-model
command:
php artisan fusion:sync-model --path=resources/content/project --create-model
The path
parameter sets the directory of the markdown files for a specific model (like article, page, post, project etc.).
The --create-model
option will generate automatically the Model file based on the content and the frontmatter section of the Markdown files.
Without the --create-model
option the fusion:sync-model
command will list some information detected from Markdown like the name of the Model and the list of the fields.
Now in your Controllers or your Blade components, you can use the Article
model with the usual method like where()
, orderBy()
etc:
$articles = \App\Models\Article
::where('published', true)
->orderBy('date')
->get();
Once you understand the basics of using Fusion with your Markdown files, you can use some of the advanced features. Consider that Fusion is a LAravel Package and during the design and the implementation of the Package we try to use and adhere to as much as possible the Laravel functionalities. With this approach, we think that we can inherit all the benefits of some Laravel features. Some of these feature that we explore and explain in the next sections are:
If you want the browser to automatically reload the pages when you change some content in the Markdown files you can set the refresh
option in the laravel
Vite plugin.
In the vite.config.js
file add the refresh
option with the list of the folder you want that Vite will "watch" for changes and reload the page.
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';
export default defineConfig({
plugins: [
laravel({
input: ["resources/css/app.css", "resources/js/app.js"],
refresh: [
{
paths: ["resources/content/**"],
},
],
}),
]
});
In the example, the resources/content
directory is added.
If you need to setup the Vite asset bundling you can take a look at the LAravel documentation: https://laravel.com/docs/11.x/vite
If you want to use date (or date-time) in your front matter you can use the format YYYY-MM-DD in the Frontmatter for example:
---
date: 2023-01-26
title: Example title for article 1
---
This is the **Markdown**.
Then in the Model you can set the casting in this way:
protected function casts(): array
{
return [
'date' => 'datetime:Y-m-d',
];
}
Where date
is the field name, the same name you are using in the Markdown.
If you are adding a new field, remember to add the field name in the list of the frontmatter field in the frontmatterFields()
function in the Model:
public function frontmatterFields(): array
{
return [
"title", "date", "excerpt", "published", "highlight", "head"
];
}
If you are interested into exploring more the attribute casting in the Laravel Model you can take a look at The Laravel Eloquent attribute casting documentation.
If you need to manage complex data in the Markdown, like for example a list of tags you can use the arrays in the Frontmatter:
---
date: 2023-01-26
title: Example title for article 1
excerpt: This will be a short excerpt from article number 1.
published: true
highlight: true
head:
- tag: title
content: Custom about title
- tag: title2
content: Custom about title2
---
# Article 1
Markdown goes here
In the example, we are adding a field named head
which is an array of values for tag and content.
In the Model file, you have to cast properly the head
field as collection
.
protected function casts(): array
{
return [
'head' => 'collection',
'date' => 'datetime:Y-m-d',
];
}
So that in your blade files, you can loop through the head
field and access to tag
or content
sub-fields:
@if (! is_null($article->head))
@foreach ($article->head as $headItems)
<div class="mx-3 px-8 badge badge-neutral">{{ $headItems["tag"] }}</div>
@endforeach
@else
<div class="mx-3 px-8 badge badge-ghost">No Tag</div>
@endif
By default, the slug of a content is the filename without the extension.
Now you can customize the slug using the frontmatter attribute slug
.
For example:
---
date: 2023-04-13
slug: fusion
name: Fusion
claim: build Website with Markdown files
excerpt: Fusion integrates Markdown into Laravel Models, simplifying Website development.
published: true
highlight: true
image: /img/fusion-cover-website.webp
tags:
- tag: Laravel
- tag: Website Development
---
# Fusion
Fusion aids in website development by integrating the power of Markdown and Frontmatter, enabling developers to create content-driven Web sites without having to manage databases.
To inspect the Markdown files and show and list the Frontmatter fields you can use the Artisan command fusion:check
.
php artisan fusion:check
To inspect the Model file and check if it extends the right class and uses the proper Traits to be a Model compatible with Markdown files, you can use the fusion:check-model
command:
php artisan fusion:check-model --model="App\Models\Article"
The output will tell you if your model is correct or not:
Parsing the Model File
Class App\Models\Article exists
App\Models\Article extends correctly the class HiFolks\Fusion\Models\FusionBaseModel
App\Models\Article uses HiFolks\Fusion\Traits\FusionModelTrait
composer test
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security-related issues, please open an issue in the tracker using the "New issue" functionality.
The MIT License (MIT). Please see License File for more information.
We built this Open Source project using some nice and powerful Open Source libraries like:
This package was generated using the Laravel Package Boilerplate.