Kludgy CMS

2014-05-03 by Jesse Spillane

About

Kludgy CMS is a static CMS/blog generator written in bash script. It takes markdown files (.md) as input and generates a static website which can be uploaded to a web server.

Requirements

You need some sort of unix-y environment with access to grep, gawk, sed, cat, perl etc.

I've confirmed that you can get this to work using cygwin on windows.

Source Code

Kludgy CMS source code

Installation

Put the contents of the repository in a directory on your computer. DONE!

You can either download the contents.

Using Kludgy CMS

Project Layout

The project is laid out as follows:

----------------------------------------------------------------------------
generate_site                    Script for generating the site
----------------------------------------------------------------------------
site_config                      Global config variables
----------------------------------------------------------------------------
Markdown.pl                      Script for generating markdown used by 
                                 generate_site script
----------------------------------------------------------------------------
markdown                         Folder containing markdown files
----------------------------------------------------------------------------
  index.md                       Sample markdown file
----------------------------------------------------------------------------
template                         Files pertaining to site template and style
----------------------------------------------------------------------------
  header                         Header file for your layout.
----------------------------------------------------------------------------
  footer                         Footer file for your layout.
----------------------------------------------------------------------------
  comments                       Template file for your external
                                 comment code
----------------------------------------------------------------------------
site                             folder where generated website
                                 will go

Global Site Configuration

In the site_config file, you can specify various global config variables. These are key/value pairs separated by ":". Below is a sample configuration file with mandatory values:

base_url:http://www.yoururlhere.com
author:MacGyver
site_name:Kludgy CMS
site_description:Kludgy CMS is a static site/blog generator that only a mother could love
comments_on:N

base_url is the domain of the website you are publishing to. urls.
author is the name of the person writing the site.
site_name is the site's name.
site_description describes the website.
comments_on , if set to 'Y' will put code from template/comments wherever {{%comments}} is. If set to anything else, comments will not be shown

All of these variables can be used in the templates or content by using the form: {{$var_name}}. These variables apply to all pages unless overridden in the individual markdown files if you want specific options per file.

Template Configuration

In the template directory there are a few files. 'header' is a file that is always put at the top of your generated html files and 'footer' at the bottom. You can edit these files to change how your site is formatted.

header and footer can contain configuration variables in the format:

{{$var_name}}

Configuration variables can be specified in both the site_config file and also the individual markdown files. For markdown files, the configuration is specified at the top html comment of a markdown file. More on this later.

You can include {{%rss_links}} to include rss links in your header.

style.css is your style sheet file. It is automatically copied into your 'site' directory when generating the site.

Write Content

In order to create a website:

Create markdown files (with .md extension) in the markdown folder. Each markdown file must have configuration specified at top. This consists of an html comment with configuration variables. For example:
```

```
This configuration will take anything found in the template/header, template/footer, and the current markdown file in the format {{$title}} and replace it with the "Did this fish just ruin the fishing industry? Here are 29 reasons why".

With the basic template provided, "title" replaces text in the template's <title> html tag as well as at the very top of your markdown file. And with that you can write a buzzfeed-esk blog post in markdown!

In addition to the template variable replacement, "category" has special meaning. Categories organize what type of content a markdown file is. We can configure a page to show all pages in a given category or show an rss feed. More on this later.

Date also has special meaning when showing all pages in a category or generating an rss feed.

Description is used for rss feeds.

image can be optionally set if you want a custom image next to a list of category pages. If not set, a default image will be used.

All these values are optional, although, if you want a page to be part of an rss feed, you must use all of them. If a page or a template has variables in them and you fail to supply an argument, that variable will not be replaced.

I'm not going to go into how to write markdown. For that, visit the markdown website
run ./generate_site. This will create html files based on all the markdown files, apply the template to those files, replace template configuration variables found in the markdown or template files and place the output in the 'site' directory.
view html site in 'site' directory. Check if the files display correctly.

Showing lists of pages in a category

Use {{%list:your_category}} to show all pages in a given category. This will put the pages in reverse chronological order and provide an rss link.

This includes an image next to each blog post. You can specify an image per page, by setting the "image" page variable. If not set, a default image will be used.

Comments

If you want to add comments, you can put {{%comments}} anywhere in template files or your markdown files. This will be replaced with the content in your template/comments file, if the global configuration varable comments_on is set to 'Y'.

Publish the site to neocities

With the publish_site bash script, you can publish your site to neocities.

To publish the website, run "./publish_site". Before doing, so the following setup is required:

Add an empty file named current_checksums.txt to your neocities website.
Open the publish_site script and update the checksum_url variable to the location of your current_checksums.txt file on your site.

When you run, publish_site, the script will download the checksums of the files currently on the neocities website. The script will generate checksums of the local generated site files. If any of the file checksums have changed, they will be uploaded via curl using the neocities api. If any files are detected on the server that aren't local, they will be removed from the server.

Comments/Questions?