Makesite

2023-06-25

• Documentation
  • Basics
  • Configuration
  • Tags
• Usage
  • Dependencies
  • Tutorial
  • Customization
  • Deployment
  • Limitations
• Developement

Documentation

Basics

Makesite is a static-site-generator based on a mere Makefile. The content of the website must be located in a directory called pages. The result of the compilation will be located in the public directory. During the compilation, Makesite will keep intermediate files in the build directory. This way it does not have to recompile everything on each call. Lastly the templates directory contains the view and layout files in their respective folders.

Here is a summary of the tree structure’s directories:

.
├── Makefile                # This file
├── build                   # Intermediate build files
├── pages                   # Pages content
├── public                  # Public website root
└── templates
    ├── layout              # Layout files
    └── view                # View files

In the pages directory, every folder is a page. Thus a page’s URL is its path. The content of a page is rendered from every *.md, *.html, and image files it contains, to which a list of the subpages is appended. Each *.js, *.css files and the favicon.* it contains are automatically added to the current page and all of its children.

There is one exception to this principle: each page can have an assets folder that is ignored. This folder can be used to store images or scripts that wont be automatically included in the content so that they can manually be included as needed.

Configuration

Each page can contain a config file to override the default variables. Here is a sample page’s config file containing all the variables you can define inside (all of them are optional):

# var         example                               default
title       = Home                                # (capitalized dir name)
layout      = page                                # (root layout)
view        = list                                # (root view)
date        = 2021-04-12                          # (dir mtime)
keywords    = makefile,static-site-generator
description = Home page of the Makesite's website
sort        = date/desc                           # title/asc
feed        = 1
cover       = assets/image.jpg                    # cover.*

There is a “root config file” at the same level as this file that contains the website’s global configuration. Here are the variables that can be set inside (all of them are optional):

sitename = Makesite
scheme = https
domain = club1.fr
basepath = some/sub/folder
authorname = nicolas
authoremail = nicolas@club1.fr
layout = custom
view = title
dateformat = %d/%m/%y
imagesext = png|gif
markdownc = cmark
loglevel = debug

Tags

It is possible to add tags to a page by adding each of them in a new line of its tags file. These tags will replace the {{tags}} portion of the layout and provides another way to browse the website. An atom/rss feed is generated for each tag and made autodiscoverable.

Usage

Dependencies

Makesite requires the following programs to be in the PATH:

• make (obviously)
• coreutils
• sed

These programs are optional dependencies for some features to work properly:

• discount for markdown render and docs.
• busybox for test server.
• fswatch for files watcher.
• rsync as the default deploy command

Tutorial

Download the latest version of this file in an empty directory and run it:

wget https://github.com/n-peugnet/makesite/raw/master/Makefile
make

This will create the base directory structure detailled above and the first page of your website: index.html in the public directory. To browse the website you will have to make it accessible with a webserver. For this, you can use the test server (requires busybox, ctrl+c to stop):

make serve

To add content to the home page you can add a .html file in the pages folder then run makesite once again, but this time in watch mode (requires fswatch, ctrl+c to stop):

make watch

This mode will automatically rebuild the site on file changes. It is possible to run both of these commands at once using make run.

You can also add new directories in pages to create new pages. Makesite will automatically add links in the parent page and breadcrumbs to every pages to make your website fully navigable. For this feature to work properly you will have to set the basepath variable accordingly.

If you deleted some files from the pages directory, they will not be used anymore but they will still be present in public. If you want to fully delete them, then it is better to run:

make siteclean
make

Tip: If your computer has multiple cores, you can use -j option of Make to speed up the build, for instance:

make -j4

Customization

It is of course possible to customize the website created by a great extent. Any number of templates can be added in their respective folder and used in specific pages or all of them using the layout and view variables of the according config file.

Styles can also be easily defined for one or a set of pages by adding *.css files in the pages folders.

Deployment

The command deploy makes deployments easy. It uses rsync by default so you just have to set the variable deploydest in the root config to make it work. If rsync is not enough, you can define a custom command in deploycmd.

Limitations

A static-site-generator based on a Makefile is not really the sanest idea. This is why Makesite has some serious limitations. Here is the full list:

• The   character is not allowed in any file or folder name (and the use of any special character is strongly discouraged). Instead you can use the character _ which will be converted to space in the default title.
• The $ character must be written $$ in config files not to be interpreted as a variable in Makesite.
• Relative path in content (images,links,…) must start with ./ or ../.

Developement

Code style:

• Tab is 8 spaces.
• Max width is 80 columns.
• Configurable variables are [a-z] other variables are SCREAMING_SNAKE_CASE.

The set of targets under dev/ are there to help developers. The init one will create a basic dev environment.

make dev/init