Ye' Olde Site By Joby

Getting started

This guide assumes a basic working knowledge of Git, Github, and Composer.

System requirements

The system requirements for Leafcutter are extremely minimal. All that's required is a web server running PHP >=7.1, and either Apache with mod_rewrite enabled via .htaccess or some other web server that supports URL rewriting (although configuring other servers is outside the scope of this guide).

Creating a site

Leafcutter is designed to be installed, extended, and updated entirely using Composer. As such, the preferred method for getting started is to create a new project by copying the site template. The suggested method is to copy the template into your own account using Github's template feature, in which case you simply click "Use this template" on the template repo page, and Github will walk you through creating your own copy.

The site template is designed to serve everything out of the web directory, and is intended to be used with web as the document root, and the root of the project not exposed to the web. This behavior can be changed, but the process for doing so is outside the scope of this guide.

Basic configuration

Leafcutter loads and merges the content of every config file in config/. You could technically have a single config file, but splitting your config across multiple files is helpful for keeping the scope/size of each config file reasonable and manageable.

The only configuration that is strictly necessary to get your site running is to tell Leafcutter the base URL of the site. This is by default configured in config/basics.yaml under site.url.

config/basics.yaml is also where you set the name of your site, as it will be displayed in the page headers and titles.

Core concepts

Content directory

A freshly created site template will have a directory named content. This is where you will keep your site's content, which will primarily be composed of .md markdown files.

You can also place images and CSS/JS files here, and create links to them using Markdown as you normally would. Leafcutter will copy them into the public web directory, and apply any required/requested preprocessing on them, such as minifying or cropping/resizing images.

Public URLs

All content files will be presented publicly as if they have a .html file extension. This is important because it allows static caching of site pages. So, for example, a file named content/some-dir/some-page.md would become publicly available as yoursite.com/some-dir/some-page.html.

index.md files will also work the same as an index.html file would in most web servers. For example, a file named content/some-dir/index.md would become publicly available as yoursite.com/some-dir/.

Asset files

Non-page content files, such as images, will be given non-human-readable URLs based on hashes of their content. By default they will be placed in web/assets/ and as such served out of yoursite.com/assets/.