Content Markdown
Table of Contents
This Laravel package with allow you to add a lightweight CMS to your Laravel application. This package will allow you to create markdown files in your Laravel application and then display the content on the front end of your website.
It works by writing in markdown files and then index the slug into the database. This will allow you to query on this slug to get the content of the markdown file.
Installation
Install the package via composer:
composer require paulund/content-markdown
Publish the configuration file:
php artisan vendor:publish --provider="Paulund\ContentMarkdown\ContentMarkdownServiceProvider"
php artisan migrate
Setup
Add Filesystem Disk
Add the following to your config/filesystems.php file:
'disks' => [
'content' => [
'driver' => 'local',
'root' => storage_path('content'),
'visibility' => 'private',
'serve' => false,
'throw' => false,
],
],
This means you need to create a folder in the storage directory called content where you can store your markdown files.
├── storage/
│ └── content/
You can also add sub categories to the content folder to organise your markdown files.
├── storage/
│ └── content/
│ └── blog/
│ └── portfolio/
Setup Database Configuration
Content markdown consists of 3 database tables, content, tags and content_tags. You can create these tables by running the migration:
php artisan migrate
In the config file you can customise the database table names.
'database' => [
'connection' => env('CONTENT_DATABASE_CONNECTION', 'sqlite'),
'content_table_name' => env('CONTENT_DATABASE_TABLE', 'contents'),
'tags_table_name' => env('TAG_DATABASE_TABLE', 'tags'),
'content_tags_table_name' => env('CONTENT_TAGS_DATABASE_TABLE', 'content_tag'),
],
Draft Posts
There are a few ways that you can define a post as a draft.
- In the frontmatter you can use
published: false - Prefixing the file with
.will make the file a draft
You can customise the prefix in the config file.
'drafts' => [
'prefix' => '.',
],
Commonmark Configuration
This package uses commonmark to parse the markdown files. You can customise the configuration of commonmark in the config file.
'commonmark' => [
'config' => [
'heading_permalink' => [
'html_class' => 'heading-permalink',
'id_prefix' => 'content',
'apply_id_to_heading' => true,
'heading_class' => '',
'fragment_prefix' => 'content',
'insert' => 'after',
'min_heading_level' => 1,
'max_heading_level' => 6,
'title' => 'Permalink',
'symbol' => '#',
'aria_hidden' => true,
],
],
],
Content Properties
- title - The title of the content
- slug - The slug of the content (optional)
- tags - The tags of the content in array format, can also be string format
- published - A boolean to define if the content is published
- createdAt - The date the content was created
- description - Meta description of the post
---
title: Content Title
slug: content-slug
tags:
- blog
- writing
published: true
createdAt: 2022-09-03 15:00:00
description: This is the meta description of the post
---
---
title: Content Title
slug: content-slug
tags: blog
published: true
createdAt: 2022-09-03 15:00:00
description: This is the meta description of the post
---
Usage
Index Command
The index command will take the markdown files in the filesystem disk and index the file in the database.
Whenever a new markdown files is created you need to run this command to index the file.
php artisan content:index
This will also run nightly to ensure the index stays up to date.
Get All Content
In order to display all of the content you can use the Content model to fetch the content.
Content::get();
Get All Content In Folder
You can organise your markdown files into different folders in the filesystem disk. You can query the content by folder.
Content::folder('blog')->get();
Get The Latest 10 Content
You can limit the number of content that is returned by using the limit method.
Content::latest()->limit(10)->get();
Get Content By Slug
You can query the content by the slug of the markdown file.
Content::slug('content-slug')->first();
Get Content By Tag
You can query the content by the tag of the markdown file.
Content::hasTag('blog')->get();
Display Content
Once you have found your content model in the database you can fetch the model and use the following properties.
$content = Content::slug('content-slug')->first();
echo $content->title;
echo $content->description;
echo $content->content;
Content Cache
Whenever you make a request the application will need to lookup the database but the slug of the file, then
lookup the markdown file, then parse the markdown to display it. This can add some latency to the request. To
speed up the request you can cache the content using the CacheResponse middleware.
Route::get('/content/{slug}', function ($slug) {
$content = Content::slug($slug)->first();
return response()->json($content);
})->middleware(\Paulund\ContentMarkdown\Http\Middleware\CacheResponse::class);
This will cache the response for 1 hour using the file store.
If you want to customise the cache settings you can change the store and the ttl.
/*
|--------------------------------------------------------------------------
| Cache Configuration
|--------------------------------------------------------------------------
|
| Configure the Cache for your content. This is enabled by middleware
|
*/
'cache' => [
/**
* Enable or disable the cache
*/
'enabled' => env('CONTENT_CACHE_ENABLED', true),
/**
* Cache store to use
*/
'store' => env('CONTENT_CACHE_STORE', 'file'),
/**
* Seconds to cache the content for 3600 = 1 hour
*/
'ttl' => env('CONTENT_CACHE_TTL', 3600),
]
By default content cache is enabled, but there is a config option to disable it, in your .env file you can add:
CONTENT_CACHE_ENABLED=false
On Deployment
After deployment of your application you can run the index command to index all the markdown files, you will also want to run a few other commands to optimise the application.
php artisan optimize
php artisan cache:clear file
php artisan content:index
Testing
vendor/bin/testbench workbench:install
composer test
Credits
License
The MIT License (MIT). Please see License File for more information.