Types of Article File

There are two main types of file you’ll work with: posts and pages. Whilst the definitions are actually arbitrary, I’m referring to posts as dated, blog-style articles and pages as undated, standalone articles.

File Extensions

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

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 http://your-site.com/test-post-1.html.

Pages

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 http://your-site.com/my-page.html.

A page called my/sub/dir/my-page.md in the root directory would become http://your-site.com/my/sub/dir/my-page.html.

Other Types of File

Templates

The _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.

The _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 _layouts directory.

Assets

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

The 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/caticons and 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 tags and 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.