PowerSite is a simple, blog-aware static site generator in .Net, written as a PowerShell module.
It currently supports authoring posts and pages in markdown, and templates and themes in Razor, but I have plans to extend that (and there's already plugin support).
There are a lot of things still to do -- but I'm not going to write about that here, that's what issues are for.
There's a bunch of conventions and configuration that go into a site. The following folders are specially named:
Also note: output is rendered into the "cache" folder which is renamed to "output" if and when everything succeeds, so don't put anything in those folders either...
Types of Content
There are three types of content in PowerSite:
Static content are the files in the \static folder and it's subfolders, which are copied directly to the output, preserving paths. You can put anything in here that you like, but the traditional use is to put create folders for images, downloads, etc.
Pages are the files in the
\pages folder and it's subfolders.
\static content, files in pages are output according to the path that they're in,
so if you have a
\pages\index.md it will be the root
\index.html of your site after rendering,
\pages\PoshSite\index.md will output in a "PoshSite" subdirectory.
However, unlike the static files, these are usually markdown files which processed by the renderer,
and then wrapped in the "page" layout template. If you have HTML files you don't want processed,
you should put them in
\static -- the pages content allows you to create absolutely any structure
you want for your site in the pages, while still getting the benefit of markdown and layout templates.
Posts are the blog post files in the
\posts folder. There's no support for subfolders here, so each
post must have a unique name. These are usually markdown files which are processed by the renderer and
then wrapped in the "post" layout template. The output location is calculated as RootUrl + BlogUrl + Slug,
where the slug is calculated from the file name by removing
Writing a Page or a Post
Each post starts with an (optional) YAML metadata header composed of key: value pairs. If the first line is three dashes (---) then the metadata continues until another line which is just three dashes. Otherwise, the metadata starts at the first line of the file and continues until there's a blank line, or any other line that doesn't follow the key:value syntax. Note that keys can't have spaces, but values can. All metadata is passed to any rendering engines and templates in your theme (see Themeing, below) for use there.
The default Metadata fields (which you really should provide) are:
date: yyyy-mm-dd hh:mm author: Author Name tags: Tag, Another Tag
Name the file with the slug and the markup type. For instance hello-world.md for a markdown post. If you don't want it published yet, name it with ".draft." in the name, like: hello-world.draft.md
Posts also support the title field to override the file name (the file name will still be used for the slug, but the title will be rendered in the template).
Themes and Layouts
Each folder in the Themes subfolder is a theme, and the active theme is selected by the "theme" setting in the config.psd1
Subfolders in each theme are output to the site preserving paths, and files which need processing are processed (currently we only support razor templates, but we should add mustache, as well as non-template langauages like less and sass).
The core template files are the output types: "post" and "page" as well as "archive" for lists and "feed" for rss/atom feeds. The index (and feed: todo) templates are generated for the whole site, (and for each tag and author: todo).
Any additional template files are used only for includes in the core templates.
Font and image files, as well as css and js are output untouched (preserving paths).