aheenam / mozhi

A Laravel package for a static file based CMS

Do not use in production yet

Mozhi

The package provides a simple way to add a static files based CMS to your Laravel project. It uses Markdown files as the content provider and uses Laravel's Blade for templating.

Requirements

This package requires PHP 7.2 and a Laravel version >= 5.7.

Installation

You can install the package via composer:

composer require aheenam/mozhi

Configuration

Mozhi comes with a set of configuration possibilities, so make sure to check the config file's content:

<?php

return [

    /**
     * The name of the disk Laravel's filesystem should use to search
     * for the content files. Mozhi expects a content directory inside of
     * the disk where the contents a located
     *
     * Default is set to local, that means storage_path('app/')
     * will be used to look for a contents directory
     */
    'content_disk' => env('MOZHI_CONTENT_DISK', 'local'),

    /**
     * the path where the themes are located, must be relative to the
     * base_path
     */
    'theme_path' => env('MOZHI_THEME_PATH', 'resources/themes/'),

    /**
     * The name of the theme that should be used to render the views
     */
    'theme' => env('MOZHI_THEME', 'default'),

    /**
     * The name of the template that should be used if no template was defined
     * in the page's markdown file
     */
    'default_template' => env('MOZHI_DEFAULT_TEMPLATE', 'page'),

    /**
     * Add all the CommonMark extension you want to use
     */
    'markdown_extensions' => [
        new \Webuni\CommonMark\TableExtension\TableExtension()
    ]

];

All the keys are commented well enough, so the usage should not be too tough. If there is something not that clear, feel free to post an issue.

As you see all the config variables can be set using the env file, but if you want, you can also publish them to change the values.

$ php artisan vendor:publish --provider="Aheenam\Mozhi\MozhiServiceProvider"

Usage

After the setup all of your routes will be caught by Mozhi and the package will try to find the appropriate content file for it.

Consider the config as above and then a call to /blog/awesome-blog. Now Mozhi will look for a file in storage/contents/blog/ that is named awesome-blog.md.

If it is found, it will render the specified template of the currenty theme and pass the content and the header of the markdown file.

The MarkDown files are parsed using Spatie's awesome package called YAML Front Matter before parsing the markdown, so you can (and should decorate) your markdown files.

So in your template file you can use the $content and the $meta variables. First is the html of the content file and $meta is an array of all header data specified in the Markdown file.

Note: If no template was specified it will fallback to the default_theme specified in the config.

Parsing Markdown

Mozhi uses the CommonMark implementation of The PHP League to parse Markdown to HTML. They offer a way to extend the specification. Mozhi uses the Table Extension by default, but you can manage all the extension by changing the markdown_extensions array in the config.

Changelog

Check CHANGELOG for the changelog

Testing

To run tests use

$ composer test

Contributing

Security

If you discover any security related issues, please email [email protected] or use the issue tracker of GitHub.

About

Aheenam is a small company from NRW, Germany creating custom digital solutions. Visit our website to find out more about us.

License

The MIT License (MIT). Please see License File for more information.

mozhi's Issues

Feature: Snippets

Currently a page contains a single .md file only. But a normal website has more than a single content field. For example a page can have multiple columns with different dynamic contents:

Introduction snippets

With snippets one can use a single Blade directive @snippet to render a snippet. The snippets are just other template-files located in the same directory as the page, but the name will be prefixed by snippet.

---

For example in a directory there is a awesome.md and a two files snippet-mega.md and snippet-super.md. When you now use @snippet('mega') in a template file the content of snippet-mega.md will be rendered.

In the background, the TemplateRenderer collects all snippet files of the current directory and creates a collection of Snippet instances. And the Blade directive just runs <?php echo $snippets[$var]->render(); ?>

Feature: Set partial configs

One should be able to set some config somewhere in the content tree.

For example, consider having a content structure like this:

|-- de
|    |-- seite-1
|    |-- seite-2
|-- en
|    |-- page-1
|    |-- page-2

One should be able to set e.g. the apps locale to de when on the de/ branch and to en when on the en/ branch of the tree ...

Feature: Sortable contents

Currently the content pages stored in the same directory have no specific sort order. But there should be a way so that the Menu implemented in #2 can be used to render the menu in a desired order.

The first idea is to simply add a prefix to the filenames: 1-index.md is the first page and 2-test.md is the second page ... Therefore one must update the RouteResolver, but you would not need any extra configuration file.

Feature: Menu

Every page should be rendered with an instance of a Menu class that is in charge for handling the page structure based tasks.

For example $menu->all() should return all pages and $menu->current() should return the current page.

One should be possible to render a menu using the functions Menu has to offer:

• get all pages and their children
• get the current page
• get all ancestors/decendants/siblings of a given page

Sitemap Generator

We need a console command that generates a sitemap of all pages. This can be done using spatie/laravel-sitemap, where one should not use the generator, but create a custom one that loops through all pages and adds them to the generator.

Then it will be written to a file that the use has specified.

Upgrade to Laravel 5.6

Upgrade to Laravel 5.6.

Feature: Handle images

Mozhi should provide a route to handle images. One should be able to set a route like images/ and Mozhi will then react on every of these following requests:

• /images/{image-name.png}
• /images/{width}/0/{image-name.png}
• /images/0/{height}/{image-name.png}
• /images/{width}/{height}/{image-name.png}

Based on the route it returns the image in the appropriate sizing.

The user should be able to define the base route for the images like images/ in the example above, but also the name of the storage for image

Upgrade to Laravel 5.7

Drops 5.5 support.

Custom routes

Currently the package catches every route and tries to get the appropriate *.md file for it. That makes it quite difficut to add custom routes with custom functionality.

Instead it would be better, if we could add the mozhi route handler at any place of the project using a simple call of a function. Something like Mozhi::routes()

Using this we could for example realize that Mozhi does only get initialized withing a route group

Route::prefix('cms')->group(function () {
  Mozhi::routes();
});

Using this way would also make it possible to add custom routes:

Route::get('/custom-stuff', function() {
  echo 'This is a custom route';
});

Mozhi::routes();

Configureable Markdown parser

Currently, the phpleague/commonmark package is loaded directly into the Page model to convert the markdown files to HTML. This way one can not use other markdown flavors.

To make it possible, one should be able to set the Markdown-Converter either as a config setting or it should be replaceable through dependency injection.