Getting Started with Code52’s Pretzel: static site generator

Preface

Having to maintain both a CMS (Umbraco) & a blogging platform (FunnelWeb) is not an easy feat. That’s why companies and corporates have teams running and maintaining their websites. Thus, I started to look for a simpler platform that wouldn’t require me to constantly be upgrading the underlying system and rely on a database.

Database are great, but like any system, requires effort to maintain and backing up of data. For a single person, this is not viable. This is when I started to look into static site generators. Coming from a .NET background, I naturally turned to a .NET-based solution and that’s how I reached Code52’s Pretzel static site generator.

Introduction

The Pretzel static site generator was created as a Code52 project (you can find out more about Code52 on their website ). The project is hosted on github and there has not been any major updates to the project since 2012, only a few minors fixes as can be seen from the github commit trail.

My recommendation is to choose another static site generator, one that is actively being developed and has a good community behind it such as Jekyll. However, should you choose to continue down the Pretzel path, here's a brief getting started guide that should help you hit the ground running.

Prerequisites

Building the source

Building the source is really straight-forward. The only thing to remember is to update all the packages via nuget.

Commands and Parameters

Help Command

Like any other Console application, Pretzel comes with a HELP command that will give you all the refresher information you need.

Pretzel -help
Figure 1. Output from Pretzel ‘HELP’ command.

Create Command

The Create command is the starting point to any site. You only need to run it once. It will generate a basic sample site for you.

Pretzel create -d [name you want to use for new folder]
Figure 2. Output from Pretzel ‘CREATE’ command.

Parameters/Options

-t [razor|liquid (default)] Used to specify the templating engine to use.

-d [name|current directory (default)] Used to specify a directory to create the sample site in.

-drafts Doesn’t seem to do anything from my testing. Maybe not finished functionality?

-withproject Only works with Razor engine. Creates a Visual Studio project within the _layouts folder with necessary classes and references to enable syntax highlighting when editing the layout files.

-wiki Changes the created sample site from being a blog to a wiki.

-azure Doesn’t seem to do anything from my testing. Maybe not finished functionality?

Executing the CREATE command without any parameters will generate a sample site with the following structure:

Figure 3. Directory listing of basic sample site created using Pretzel ‘CREATE’ command.

Bake Command

The BAKE Command is designed to be a once-off site generation command. I.e. When you need to regenerate the site because you’ve just fixed a typo.

Pretzel bake -d [folder name your site resides in]
Figure 4. Output from Pretzel ‘BAKE’ command.

Parameters/Options

-t Used to specify the template engine as per CREATE command. Only use this if you haven’t specified one in your _config.yml file. Note: Sites created using the CREATE command already contain a template engine entry in the generated _config.yml

-d Used to specify the root of where the site files resides.

-p Not tried this.

-drafts Not tried this.

-cleantarget Tells Pretzel to empty out target site folder which is hardcoded to be ‘_site’

-vDir Not tried this.

Executing the BAKE command will create a ‘_site’ folder in your site files directory:

Figure 5. Directory listing of basic sample site after invoking Pretzel ‘BAKE’ command.

Inside the ‘_site’ folder, you will find your generated site (the final files you will upload to your server), the sample site’s ‘_site’ directory looks like this:

Figure 6. Directory listing of generated site after invoking Pretzel ‘BAKE’ command.

Taste Command

The TASTE command is used for development purposes when you are planning on making a lot of changes. Pretzel will remain running and when it detects any changes, it will regenerate the site for you without you needing to manually run the BAKE command.

Pretzel taste -d [folder name your site resides in]
Figure 7. Output from Pretzel ‘TASTE’ command.

Parameters/Options

-t Same as BAKE command.

-d Same as BAKE command.

-p Same as BAKE command.

-drafts Same as BAKE command.

-nobrowser By default when you use the TASTE command. It would open a new browser window pointing to your site. Adding this will tell Pretzel to not open a new browser window.

-cleantarget Same as BAKE command.

-vDir Same as BAKE command.

Executing the TASTE command on the sample site with default options will open a new browser window showing the following:

Figure 8. Generated site viewed in Google Chrome.

Import Command

This command is used to import/convert existing blog data into Mark Down files to work in Pretzel. I have not used or tried it out myself.

Streamlining the workflow

Having to manually type the BAKE and TASTE commands is a real pain. So I use batch files to by pass them. Below is how I setup my batch files:

Figure 9. Directory listing showing two batch files and Pretzel.exe.

Contents of BAKE.bat:

Pretzel bake -d [folder name your site resides in] -cleantarget

Contents of TASTE.bat:

Pretzel taste -d [folder name your site resides in] -cleantarget -nobrowser

Other notes and tips

Some helpful tips I learned the hard way:

  • Do not put the Pretzel.exe file in your source directory. Otherwise Pretzel copy a copy of itself into the ‘_site’ folder.
  • Razor engine seems to have a few issues, most notable is the RSS.xml file fails parsing when you have a URL in the ‘link’ and ‘guid’ elements.
  • If you choose to use Razor engine, in RazorSiteEngine.cs add a line to the catch statement to output the offending file’s filepath. This will greatly help you identify and fix the parsing error.
  • Use server-side includes to extract common parts of your blog so that you don’t need to re-upload every single blog post when you create a new one.
  • Anything in the source site’s root directory beginning with a ‘_’ will not be copied over to ‘_site’.

Conclusion

That’s all you need to know in order to use Pretzel. Site design, etc. is up to you and the only thing left to do is just copy all the contents within the ‘_site’ folder on to your server.

Leave a Reply

Your email address will not be published. Required fields are marked *