cssitegen/Readme.md

CsSiteGen

A relatively simple (for now) static site "generator". The heavy lifting of this project is actually performed by pandoc so you better make sure you install it on your system.

How to use

The configuration for a site is stored in a file called cssitegen.json this file can technically be located anywhere but the recommended directory structure is as follows:

-Project-Root
 |
 |-Source_Directory
 | |
 | |- [source files...]
 |
 |-Destination_Directory
 |
 |-cssitegen.json

This makes the file much simpler to write, However with fully specified paths you can actually place the files anywhere.

Structure of cssitegen.json

All cssitegen.json files must specify at minimum the source, and destination directories, If the baseurl is omitted it will simply be null. You must also ensure that you follow the JSON format properly. The following fields are used in a file

• Source - a string that locates the source files. This can either be the full path or a relative path.
• Destination - As above but this is where the output files will go.
• BaseUrl - a string or null this will be used to replace the string %BASEURL% in supported files. (Depending on your usage you may need to specify the protocol)

Example file

{
    "Source" : "./Source",
    "Destination" : "./Destination",
    "BaseUrl" : "https://example.org"
}

Executing the program

Currently the program has two subcommands that can be used, and an optional project argument, if not specified the program assumes that the project is the current directory.

The program is called like this

cssitegen SUBCOMMAND [--project "directory"]

convert

This subcommand performs conversion of the files. It only considers source files for conversion if they are new or have been changed since the last run of the program. Therefore if you change the BaseUrl or the template file you will need to clean and convert your entire project. Convert also does not detect deleted source files at the moment, so you will also need to clean for that,

clean

This subcommand purges the output directory, You can of course do this manually but for convenience this is implemented here.

Templating

The templating system is managed by pandoc so please check the documentation for pandoc to learn about the format.

As for where to place the template files, for every file converted using pandoc the program will attempt to locate the appropriate template named as .template, it first looks in the directory of the source file, and then works its way up the directory tree until it hits the root directory, using the first template it finds. This means that if you want different templates for some sections of your site you can do that, and other sections will fallback to your root template. If you don't specify a template you will get the pandoc defaults

BaseUre replacement

Currently the string %BASEURL% will be replaced in .md .html and template files. This feature is something you will definitely want to use, unless you want to structure everything to the point you only need relative links. (I personally found this almost impossible)

Future plans

• Automatic page generation using pre-process steps and temporary files. E.G Contents pages, index pages etc...(DIFFICULT)
• Detection of changes to the BaseUrl and any templates. (MEDIUM)
• Detection of deleted source files and removal of the destination files.(MEDIUM)
• Allow expansion of conversion operations (DIFFICULT)
• Allow customisation of filetypes that can have %BASEURL% replaced (EASY-MEDIUM)