This project uses Stack, Pandoc, Warp and Shake
Why are you doing this?
I want a Hakyll-like static web site generator that can be easily used in conjunction with a dynamic site built with Yesod. I want it to use Pandoc so that I can build rich content, possibly with embedded mathematics. I also want it to be responsive, so that when I make changes to the underlying Markdown files, I can view the updated output in my browser quickly instead of having to wait thirty seconds for the Hakyll build to complete. There are probably tools that already do this (probably Hakyll itself can be made to do this), but I love reinventing the wheel. So, that's what I'm going to do.
The system is intended to be extensible in the future, so I will put some thought into how to extract its core functionality into a library.
Work in progress
This project is a prototype and, therefore, should not be used for any real work yet!
- Uses Pandoc to render Markdown into HTML (and, also, Microsoft Word documents)
- Supports static resources such as CSS
- Supports dynamic refresh of routes
- Shake-based build ensure that outputs are correctly maintained as long as dependencies are fully specified
Currently Pansite is a trivial web app built on top of Warp. Routes are defined in a
.pansite.yaml file using the following schema:
# $(@D) is an automatic variable meaning "the output directory" (a la GNU Make)
# All other paths are resolved relative to this directory containing this file
- path: ""
- path: page1
- path: page2
- path: css/buttondown.css
- path: $(@D)/index.html
- path: $(@D)/page1.html
- path: $(@D)/page2.html
- [css, css/buttondown.css]
path entry defines a route that the web app will respond to. The
target key defines the cached content file to return in response to this route.
The cached content files are currently built using Shake using rules generated from the
.pansite.yaml file. Thus, the app itself defines how to build the cached content files using a simple declarative format. There is a silly test site defined under
_app, specifically in
_app/.pansite.yaml that demonstrates the idea. I do not want to allow the app's content itself to provide a Shake build script since I do not want to allow the user-provided content to run arbitrary commands on my server. Instead, the simple declarative rules in
.pansite.yaml constrain what the build system can do while still keeping it useful.
Currently this prototype demonstrates the use of a single build tool, namely Pandoc. I intend to refactor the code to make it straightforward to specify additional build tools: some will be embedded directly, like Pandoc, others can use the Shake's
cmd function to invoke external processes.
Build tools currently supported:
- Pandoc (
pandoc): Process input files using Pandoc
- Copy (
copy): Copy input file to output
How to run it
Run the example site:
stack exec -- pansite --port 3000
In your web browser, navigate to a route defined in
$ stack exec -- pansite --help
Pansite development server 0.1.0.0.772a2d5 (locally modified)
Usage: pansite ([-p|--port PORT] [-c|--config CONFIG]
[-o|--output-dir OUTPUTDIR] | [-v|--version])
Run Pansite development server
-h,--help Show this help text
-p,--port PORT Port
-c,--config CONFIG Path to YAML application configuration file
-v,--version Show version
Released under MIT License
Copyright © 2017—2018 Richard Cook