heckweasel/docs/index.md

HECKWEASEL documentation!

Welcome to the index for HECKWEASEL Documentation. In this directory you'll find a bunch of files but this is the introduction you need to understanding the way heckweasel works and how to use it. You wouldn't web a site.

Introduction: TL;DR

Heckweasel compiles a set of files into a website.

There is your website template, separate files that are the content of your website (such as a blog post, an image, etc), and json files that are the metadata for each content file. These get compiled together into static web pages.

There's a lot more to it, and it is entirely programmable, but basically that's it.

Introduction: What the hyeck is Heckweasel?!

Heckweasel is a website compiler framework. Primarily it allows the creation of web site using a collection of flat files which are in a maintainable form, producing the less maintainable formats that web browsers use.

The flat files in a heckweasel project are just a directory of files like any other. There is a default directory structure for projects but that isn't important right now.

Heckweasel projects generally take the form of a collection of one or more templates and a collection of one or more files that are filled into the templates. Pervasively, heckweasel draws a distinction between the contents of a web page and the template it gets put into. You can think of the template, as generally used by heckweasel, as a sort of picture frame into which your content is placed. The content itself may be implemented as one of several popular formats such as Markdown and HTML. Also of note is that there are sort of two routes from heckweeasel input to heckweasel output, one route is through the template system and the other route merely copies the input to the output.

Another important detail about heckweasel is metadata. Every item in the heckweasel project (thus, every file in the heckweasel project directory) has a collection of metadata associated with it, such as its file name, creation time, and other objective information, but also any arbitrary information about it such as its title, a short description, thumbnails or whatever. It's also important to note that the content of a file counts as metadata, and is stored the same way inside of heckweasel's way of looking at the files. Metadata is stored with the file as filename.meta and directories contain metadata in the file called .meta. Metadata is also inherited! So setting a template in a directory's metadata will apply to all of the contents of that directory. Metadata is all in a JSON format called JStyleSon, which is JSON except you can have comments in it. All of these metadata are accessable from the templates, which leads to...

The final important detail about heckweasel is that it, at is core, uses a programmable template system called Jinja. Jinja allows a lot, and I mean a lot of flexability in the way that the output is produced, giving complete programmability. This allows templates (and pages, for that matter) to contain programmable outcomes such as showing a list of all blog entries (each of which would be a separate file), or making a thumbnail gallery from a collection of pictures, or generating an RSS feed from all of the contents of the site. This also allows the website design to be broken into parts such that commonly-used patterns can be merely included in the file rather than being written repeatedly (although normally this function done with the page templates).

Glossary

• template
  • A -link-Jinja2 file which gets filled in with your content
• content
  • The content which gets filled into templates to produce pages
• metadata
  • Extra variables or values associated with content, which can be used to modify the way template works and do other tricks

Just the very Basic Heckweasel Project

So with all of that said, the most basic possible heckweasel project that is actually functional would be something like a page template, and a content file called index. Heckweasel operates on an input directory and outputs to an output directory. This is admittedly not a normal use case since it doesn't benifit much from the elaborate system underneath, but it gets the idea across.

So you have your project directory mywebsite; inside we can have the directories source and publish, and various files, and well here's a picture:

• mywebsite
  • source
    • .meta
    • templates
      • default.jinja
    • index.md
    • index.md.meta
  • publish

To explain the various files:

.meta

This file is a JSON file containing project-wide metadata. Usually this would be metadata that applies, by default, to all files. Some things that affect the way Heckweasel processes files would be template which would set the default template to put content into and templates which would set the directory to look for templates in. By custom we also may want to set the title, author and other things like that which we may want to fill into the output files. We also put things like the eventual published address for the site (site_root).

Example .meta file:

{
    "site_root": "https://website.me",
    "author": "Very Nice Person",
    "title": "My Website"
}

default.jinja

This is the default template. Heckweasel will look for templates/default.jinja unless another templates directory and template are specified. Jinja templates might output any kind of text file you want, but usually we put HTML inside them. Here's an example default.jinja that makes a barely functional web page but we'll explain more later:

<!DOCTYPE html>
<html>
<head>
<title>{{ metadata.title }}</title>
</head>
<body>
{{content}}
</body>
</html>

The main thing to notice is that this is a very simple HTML file. It does the bare minimum to render in a browser. The next thing to notice are all of the {} things. Those are Jinja commands. A {{}} containing a name will fill that name from the variables set in the Jinja environment. In Heckweasel the main two things are content and metadata. Metadata contains the metadata set via the .meta and other sources as discussed above. The new thing here is content, which is the contents of the page! As discussed above, the contents and template are considered separately, and so the page contents are filled into the template where the {{content}} tag is! You can also see that the title of the page is set based on the page's title metadata. We'll discuss this more in the next section.

Another interesting thing is, any styling that should be applied to the whole website, to a particular page type, or whatever goes in templates. For example this is where you'd include the site-wide CSS sheet for this site, and it would apply that style to all the pages (we'll discuss this more in a future section).

index.md

This is the contents of the page that will eventually become index.html when heckweasel is done with it. Notice it is .md which means markdown, a user-friendly markup format - heckweasel will convert this to an HTML fragment and fill in the template's content with the result, producing index.html. This is how the magic happens! The contents of this file could be something as simple as:

# Welcome!

Hello this is my website! Hi!

index.md.meta

This contains the metadata specific to index.md. It can be left out if there isn't any specific metadata, but it's useful to make even an empty one for future reference. An example use of this is to set different title for each page.

Example:

{
  "title": "Welcome to my Home Page"
}

Rolling it all together

Given the above tree, from the command line in the mywebsite directory, to compile this would be as simple as :

$ python -mheckweasel source publish

This would produce, in the publish directory, index.html, which would have contents like:

<!DOCTYPE html>
<html>
<head>
<title>Welcome to my Home Page</title>
</head>
<body>
<h1>Welcome!</h1>
<p>This is my website! Hi!</p>
</body>
</html>

Notice how the result of converting index.md into HTML is inserted into the template where {{content}} was, and the value of title from index.md.meta is inserted where {{metadata.title}}. While index.md inherited the top-level title metadata from the top .meta, its own index.md.meta file overrode it. Neat!

The publish directory is ready to be serverd by a small HTTP server, placed in a web content directory, or whatever. We'll discuss that in a future section about hosting your Heckweasel site.

Getting (very slightly) more advanced with Heckweasel

Now that we see how a project and its parts fit together we can make our little website slightly more interesting.

Styling your Web Site

As we alluded to above, the templates are where style information generally lives.