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.
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.
- Visual Studio 2013, used to build the Pretzel project. If you do not have Visual Studio, I recommend you download a FREE copy of Visual Studio 2013 community edition.
- Internet access, to download the Pretzel source code off github.
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
Like any other Console application, Pretzel comes with a HELP command that will give you all the refresher information you need.
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]
-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:
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]
-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:
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:
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]
-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:
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:
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’.
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.