This guide assumes a basic working knowledge of Git, Github, and Composer.
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.
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 is also where you set the name of your site, as it will be displayed in the page headers and titles.
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.
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
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
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