CREATING A MANDY PROJECT

Getting started and creating a Mandy project. - [back]

Types of files

A Mandy project is a directory full of a very specific set of files and sub-directories. There are three types of files in every mandy project: layout files, configuration files, and content files. All these types of files are elaborated on in the following sections.

Layout files

Layout files dictate how the content you write in a content file is rendered on an HTML page. Layout files contain code that has some layout variables inside it. The code surrounding variables can be of any type since you do not have to neccessarily only render HTML. The variables inside the layout refer to content you have written or site-wide or page-wide configuration variables. For each of these two types of variables there exist two namespaces: page and site. Each of these namespaces have their sub-namespaces that can be accessed as outlined in the list of the sub-namespaces below:

site.config: This namespace is the top namespaces for accessing configuration variables set in config.jmu. This namespace contains variables that must be set for a Mandy project to compile. Which variables these are, is listed in the "project configuration" section.
site.config.user_config: This namespace is the namespace for user-defined site-wide variables.
site.config.iter_content: This namespace assumes that the iter_content configuration variables has been set in config.jmu and provides a namespace for looping over content files in a directory and outputting information for each content file in that directory.
page.data: A namespace that represents mandatory variables that must be set in the data section of a content file.

page.data.user_config: Much like the site-wide user_config section in the site.config namespace, this namespace represents user-defined variables for a page's data.

The section below outlines the syntax for rendering data in a layout file:

Rendering a variable: { site.config.user_config.title }
Rendering depending on a condition: {{ if site.config.user_config.is_cool_cat}} content {{ else }} content {{ endif }}
Rendering something by looping over it: {{ for post in site.config.iter_content.blog_posts }} {{ post.data.title }} {{ endfor }}

Configuration files

In a Mandy project there exist two types of configuration files: site-wide configuration and data configuration files. Both of these types of files are written in the Jirai Data Markup language

Site-wide configuration

Site-wide configuration is controlled from a file called config.jmu at the root of every Mandy project. This file has some mandatory fields that must be set and some fields that are optional. The list below outlines which variables are mandatory and which are optional:

dist_dir: This field is mandatory and tells Mandy in which directory to store the set of TML files produces by a compiled Mandy project.
copy_files: This field is optional and describes any files or directories that need to be copied to the dist_dir. This variables data type is a list of strings.
iter_content: This field is optional and describes any directories containing content files you would like to loop over. You would use this in, for example, making a blog with Mandy. This variables data type is a list of strings.
user_config: This field is optional and describes a map of key-value mappings, where the key is a string and the value is also a string. This field can be used to store additional site-wide configuration variables.

Data configuration

Data configuration files are a series of .jmu files stored in the data directory, which is at the root of a Mandy project. Having this directory with these files is completely optional. The structure of each data file is a named dictionary of a list of key-value dictionaries, where each key is a string and each key's value is also a string. The name of this list of dictionaries is alsways items. The structure of each of these dictionaries must always be the same. Values of each dictionary can be different. To loop over data stored in a data file you would loop over the site.data.data_file_name.items list. data_file_name is the name of the data file you are looping over.

Content files

Content files are written in the Extended Jirai format. These files must end in the .ejirai file extension. Each Extended Jirai file has two sections. The first section is the data section and the second is the data section. More information on how to write Extended Jirai content and the surrounding delimiters for both content and data sections can be found on the Extended Jirai specification page linked above. The data section of an Extended Jirai document is written in the Jirai Data Markup language. This data is accessed in layouts via the page.data namespace. The list below describes which variables are mandatory and which ones are optional:

layout: This field is mandatory and describes which one of the layouts in the layouts is to be used to render the content for the current document. The layout's name is provided without any file extensions.
title: This field is mandatory and describes the title of the page.
description: This field is mandatory and is a short summary of the content in the current file.
user_config: This field is optional and contains a list of key-value mappings, where the key is a string and the value is a string. Each mapping in this list represents any optional data the user would like to add for this specific page.

ALYX SHANG