MANDY ⚡ 🌸 🎀

A fast and light static-site generator. ⚡ 🌸 🎀

ABOUT 📚

This repository contains the source code for a light and fast static-site generator (SSG) using the Jirai markup language and the JMU data language. The SSG has been optimized to be exceptionally light and exceptionally fast.

INSTALLATION 📥

There are two options for installing Mandy: i) Installing Mandy from source or ii) Downloading and installing one of the pre-compiled binaries.

From source

This guide assumes that you have the following tools installed and available from the command line:

• RustC and Cargo
• Git

To install Mandy, execute this command from the command line:

cargo install --git https://source.alyxshang.boo/alyxshang/mandy --tag v.0.2.0

From a pre-compiled binary

There a pre-compiled binaries for the following platforms:

• Mac OS for Intel chips: Download the appropriate executable from here, rename it, and place it in a directory on your $PATH.
• Mac OS for Apple chips: Download the appropriate executable from here, rename it, and place it in a directory on your $PATH.
• Debian for 64-bit chips: Download the file ending in .deb from here and install it with the command sudo dpkg -i file_name.deb, where file_name is the name of the file ending in .deb.
• Arch Linux for 64-bit chips: Download the file ending in .pkg.tar.zst from here and install it with the command sudo pacman -U file_name.pkg.tar.zst, where file_name is the name of the file ending in .pkg.tar.zst.
• Windows for 64-bit chips: Download the appropriate executable from here, rename it, and place it in a directory on your $PATH.

CODE REPORT 👩‍💻

Mandy was built with the explicit purpose of being very light, highly optimized, and very fast. These metrics about the project's code should illustrate this:

• 700 lines of Rust.
• 160 lines of Rust unit tests.
• 779 lines of documentation comments.
• The size of the compiled binary is less than 500KB.
• The build time for a Mandy project is <400ms.

The previous version of Mandy from two years ago had 4000 lines of code and an executable size of 12MB.

USAGE 🔨

CLI commands

Mandy's CLI offers four commands:

• help: Outputs usage information.
• version: Outputs version information.
• test /path/to/project: Tests whether the Mandy project at path /path/to/project can be compiled.
• build /path/to/project: Compiles the Mandy project at the path /path/to/project.
• clean /path/to/project: Removes the directory and the items at the path /path/to/project/$DIST_DIR. The $DIST_DIR is set via the dist_dir variable in the configuration file of a Mandy project.

Mandy project structure

The only task of Mandy is to take content written in the Extended Jirai format, some HTML templating code, and a configuration file and use this information to produce a directory containing HTML files and other assets, if specified, and make these available and ready to serve as a fully-functional website. This directory with static HTML files and other assets will henceforth be referred to as a compiled Mandy project.

Each Mandy project contains three types of files:

• config.jmu: A file containing simple key-value pairs describing configuration variables for a Mandy project. The format of this file is the Jirai Markup Language.
• page.layout: This file type describes how the content inside a Mandy project is supposed to be laid out on a finished website.
• content.ejirai: *.ejirai files are the main characters in a Mandy project. They contain the content that a finished website displays. These files are written in the Extended Jirai format.
• data.jmu: A file containing a key that must be called items located in the data directory of a Mandy project and gives users the ability to store any extra data that can only be stored as a list of data dictionaries.

Configuration files

The configuration file of a Mandy project is written in the Jirai Markup Language format (JMU). JMU uses simple key-value mappings to store data. Such a key-value mapping looks something like this: "name" >~< "Alyx". Each configuration file must have a few important fields. Some of these fields can be left out. A list of the optional and mandatory fields can be found below:

• dist_dir: This specifies where the compiled Mandy project is to be placed inside the project directory.
• copy_files: This field is optional but could be neccessary for copying static files to a compiled Mandy project. Typically, the directories specified here contain images or CSS.
• iter_content: This field is optional but if used, must contain a list of directories containing iterative content. Such a directory could be called posts and could contain posts on a blog.
• user_config: This field is optional but if used, contains a nested key-value mapping of any other values one might like to use on one's site.

Configuration data can be accessed by using the {site.config} namespace in layouts.

Layout files

Layout files must be stored in the layouts directory of a Mandy project and these files determine the layout of the content on a page. These files must end in the .layout extension and are HTML templates. The content is rendered through variables inside the template. These template variables are surrounded by { and }. If an item is iterated over, the open curly braces and close curly braces are doubled. The following variables are accessible inside a template:

• site.config: This variable allows access to the configuration values of a Mandy project. The site.config.iter_content.loop_dir can be looped over, if specified.
• site.page.data: This variable contains the data of each page. This shall be explained in more detail in the next section.
• site.page.url: This variable gives one the URL of a content page.
• site.page.content: This variable contains the HTML content of a page.

Content files

Each content file is written in the Extended Jirai format. This format has two sections. The first sections contains data and the second section contains content. The content is written in the Jirai format. The data section is written in the same format as the configuration file. Together, they make up Extended Jirai. Each content file must have this format and must end in the .ejirai file extension. The variables that must be set in the data section are listed below and are accessed in a template via the {page.data} variable:

• layout: This variable tells Mandy which layout must be used for laying out the content present in the file. The stem of the layout file is used and Mandy will look for a layout of that name in the layouts directory automatically.
• title: The title of the page. A title is always required and important.
• description: The description of the page. A description is always required and important.
• user_config: This variable is optional but can be used to store any additional information on the page.

Data files

Each data file is in the Jirai Markup Language format (JMU) and located in the data directory at the root of a Mandy project. Every file in this directory must have a top-level key called items and the value of this key must be a list of JMU blocks containing string key-value pairings. The name of each file must have a name of the following pattern: name.jmu. The data in this file can be accessed in layouts by iterating over the variable data.name.items.

CHANGELOG ✒️

Version 0.1.0

• Initial release.
• Initial upload to Forgejo.

Version 0.2.0

• Updated documentation.
• Added the ability to have site data in the data directory.

NOTE 📜

• Mandy ⚡ 🌸 🎀 by Alyx Shang 🖤.
• Licensed under the FSL v1.