A sensible static site generator that runs on Windows and uses Razor templates. I built it so that I could focus more time on writing content and less on fiddling with markup.
- Intuitive pathing system
- Uses Razor template syntax for layouts
- Supports reusable components
- Callbacks to resolve URLS for subdirectories
- Automatic conversion of .less files
- Automatic file regeneration via the --watch option
- New examples project: champ-examples
- Champ can be used as a library in your project. Use SiteBuilder.ProcessPageNode()
The tool is packaged as a single .exe file. Download the latest release of champ.exe from here: champ v1.0
- .Net Runtime 4.5.1
Getting started with champ is easy. Copy champ.exe into the root folder of your project, open command prompt and then create your site using the --bootstrap option:
champ will start creating all required folders and add a few example pages. Now build your site:
c:\mysite\champ.exe . <-- don't forget the period!
You won't see anything appear in the console, unless there's an error.
Hint: use the --verbose option to get (lots of) output.
Great! You're ready to view your site. Open index.html in the output directory with your favourite browser:
Now you can get editing by adding new files into the pages/ directory and running champ.exe again.
Finding Your Way Around
champ uses a combination of razor templates and markdown files to produce static .html files. It combines these files from various directories when building your site. There are three main directories in use:
pages\- to store content
templates\- to store layout templates and reusable components
pages\ directory contains your content markdown (.md) files that will be converted to HTML and combined with a template,
before being saved as a
.html file of the same name. So,
about-me.md will become
Directory paths are also mirrored, making it easy to organise your content. Given this file,
champ will create a file called
projects\foo\instructions.html. Your subdirectories are mirrored when creating your content.
The output of pages\ will also become the rooted content of your website. In other words,
pages\index.md will become
pages\company\founders.md will become
What's in a Page file?
A page file contains a section at the top which specifies the page title and template.
template maps to a
.cshtml file found in
title is the page title and used by the template.
<!-- template = page title = About Me -->
templateis optional. If you don't specify one then the template from index.md will be used. If that doesn't exist, the parent index.md will be used.
What about non-markdown files? Any file that isn't a markdown (.md) file will be copied over. This is useful when you want to send an .html file to the output directory, or need a CNAME file to enable github pages.
All layout templates and reusable components are stored here. champ doesn't support subdirectories, so all templates must reside here.
.cshtml files that can be included in a layout template, include a reusable component and also provide a hook point for injecting the markdown output.
Using Champ to Generate Content
champ.exe to regenerate your content after an edit:
champ.exe SOURCE-DIRECTORY OUTPUT-DIRECTORY
Note: champ will delete everything from the output directory before building your site. Only files and directories that start with a period (.) will be ignored.
Compilation errors are shown in the page that was trying to be created. The error page shows you the compilation error message, the offending line number and a short snippet of the broken code.
Watch for changes and automatically generate the output
The --watch option will scan the source directory for any file changes and automatically generate the new output. Use this when you're busy developing your site content and don't want to have to keep starting champ after every change.
champ.exe --watch C:\src\lukevenediger.github.io C:\src\lukevenediger.github.io-live
Downloading champ-bootstrap from a file share
You can specify a file or UNC path for the location of champ-bootstrap by using the --bootstrap-source option:
champ.exe --bootstrap --bootstrap-source \\myserver\share\champ\champ-bootstrap.zip
If you don't specify --bootstrap-source champ will try download the latest zip file from github.com.
You can find a host of examples, with source and live demo, at the champ-examples project.
There are a few ways to get help:
- Open an issue on the project
- Contact me on twitter or via email (see below)
I'd also love your suggestions and welcome any improvements you may have.
Why Champ? (plus some alternatives)
I really love the idea of pre-generated content pages as a way to make building a site much simpler, as well as freeing up cycles to be able to write more content. I looked around and saw that the really good generators such as Jekyll and Punch were unix/macos/linux focused, while windows-only options like pretzel didn't give me a good first-run experience. So, champ was born, and it suits my needs just fine. I hope it suits yours too!
These features would be great to have:
- Better support for blog articles, including RSS feed generation
- A reusable component for DISQUS comments
About the Codebase