Installation
Getting started with Cleaver takes less than five minutes. All you'll need to get going is a machine running PHP 7.1+, a fairly recent version of Node + NPM, and Composer. From your command line, run the following:
composer create-project aschmelyun/cleaver your-site-name
This will install your project inside of a folder called your-site-name. Navigate inside that folder, and still in your command line run the following. This will install the npm dependencies, compile the assets, and build your site for the first time:
npm install && npm run dev
A dist folder should now be present in your project's root directory, inside of which you'll find the compiled assets folder and a single index.html document created from the default content provided.
Adding Content
Cleaver process content from inside of the resources/content directory. Structure inside of this directory doesn't matter, and isn't mirrored to the compiled site. Instead, a path variable is set in each content item to determine the url of the final page.
You have two options when it comes to content in Cleaver, JSON or Markdown. Both have their pros and cons for each project, but for more data-driven pages JSON should be a better fit, whereas Markdown might be better for content-heavy sections of your site. Note: Regardless of the format you choose, a view variable must be set in each content item to be rendered successfully.
Here's an example of a JSON content file for Cleaver:
{
"view": "layout.blog",
"path": "/blog",
"title": "My mediocre coding blog!",
"about": "Here's where I write everything that I forgot I bookmarked."
}
And a similar example of a Markdown content file:
---
view: layout.blog
path: /blog
---
# My mediocre coding blog!
Here's where I write about everything that I forgot I bookmarked.
When you build your site, all of the keys in the entire JSON file, or the header of the Markdown files, are sent to the Blade template as individual variables.
The template used is specified in the view variable (via the structure in your resources directory). The fully-parsed HTML from the Markdown content under the heading area is accessible through a single variable called $body.
Modifying Assets
Out of the box, Cleaver comes pre-installed and pre-configured with Tailwind CSS as the front-end style framework of choice. It's included through the main app.scss file located in the resources/assets/sass directory.
If you would like to make any additions or changes to the framework used (e.g. you prefer Bootstrap), all you'll need to do is install it through npm and replace the @tailwind directives with your framework of choice's includes. Because the entire asset pipeline is run through Mix (webpack), it's really easy to make large changes like that.
Additionally, we've included a very small bootstrapped app.js file in the resources/assets/js directory. It simply adds in lodash and jQuery globally to your site, feel free to extend or remove this functionality as you see fit.
Cleaver also leverages Mix's versioning, and thus references a mix-manifest.json file at the root of your project. These values are changes with each build, and are injected as an array with the $mix variable across all Blade templates. You can see how the CSS files are pulled in using this by checking out the default layout file, and the JS inside the footer include.
Content Collection
As of version 1.4, there's now a $cleaver variable injected into every view (Blade template) across your site. This variable contains a Collection (much like an Eloquent collection in Laravel) which holds all the content from every file under your /resources/content directory.
This enables you to use any Collection method to organize, sort, filter, and map the pages available in your site across any view. For example, let's say that you have a blog and want to have a sidebar that shows your latest 5 posts. Instead of having to manually update this every time you add a new post, you can call the $cleaver collection, sort by latest publish date, filter out just the ones that use a blog layout, and limit it to 5 items. You can then loop through this collection just like you would an array, and output links to each of those articles.
Now, each time that you add a post to your site that matches the credentials you're filtering for, Cleaver automatically grabs your collection of files during compilation and outputs the appropriate list in your sidebar.
Building Your Site
Once you're ready to compile your assets and build your site, you have three options to choose from. The following command will build development assets and compile your site into an HTML folder structure located in the /dist folder:
Leveraging Mix's watch functionality, running this command will start a local server that keeps an eye on every file inside your /resources directory. It will then automatically re-compile the assets and site HTML each time a change has been saved:
Finally, when you're ready to deploy your site, run this command to compile the assets, perform minification on the CSS/JS, and output everything to the /dist folder:
Deployment
Once you're done, deployment is super simple. Either upload your entire project to your server of choice and point the webroot at the /dist folder, or commit just the files that are in the /dist folder themselves and save them to the default server root.