Types of Article File
There are two main types of file you’ll work with:
pages. Whilst the definitions are actually arbitrary, I’m referring to
posts as dated, blog-style articles and
pages as undated, standalone articles.
Most files you create will either have a
.md extension or a
.html extension. Files with a
.md extension are passed through a Markdown processor and files with a
.html extension are not. That’s the difference.
Posts go in the
_posts directory on the site. The example site shows a directory structure under
_posts that organises articles in to year and month. You don’t have to follow this structure but I think it’s useful.
Posts have a filename that begins with
yyyy-mm-dd- indicating the year, month and day of the post. You must follow this convention for posts.
No matter how you organise your posts under the
_posts directory, when the site is generated it will strip off the date at the front of the file name and move the file into the web root. So, if for example you have a post in
_posts/2018/10/2018-10-02-test-post-1.md it will generate a file in the root directory of the web server at
Pages can go anywhere on your site. Their file names do not have to begin with a date. Pages are not automatically copied to the root of the web server either; they will follow the directory convention you use.
A page called
my-page.md in the root directory would become
A page called
my/sub/dir/my-page.md in the root directory would become
Other Types of File
_layouts directory contains your templates. These are Smarty Templates. You tell a post or page which template to generate itself through in the front matter (more about that later). Your post or page is passed through Smarty with the template you specify when it is generated.
_layouts.system directory contains default layouts. These are useful to get you started. Anything in the
_layouts directory will override an item of the same name in the
_layouts.system directory. Put all your own layouts in the
Assets are things like images and most assets can go anywhere but I’d suggest saving them under the
assets directory because you can then move them en-block if for example you chose to serve your assets from a CDN or whatever.
assets/main.scss file /must/ be where it is. This is the primary stylesheet for your site. It is an SCSS file (which can also contain pure CSS of course) and it is passed through an SCSS compiler before generating a
.css file in the output directory.
Category and Tag Icons
If you want little icons for your categories and tags, put them in the
assets/tagicons respectively. They should be .png files named as
icon_catortag.png where catortag is the slugified name of the category or tag.
Tags and Categories
If you use tags and categories (and you don’t have to) you’ll need the
cats directories too. GreenHat will automatically generate subpages in these directories, one for each tag or category listing posts under it and an index file listing all the tags or categories with post counts.