Development
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!
Current features
- 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
The vision
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
routes:
- path: ""
target: $(@D)/index.html
- path: page1
target: $(@D)/page1.html
- path: page2
target: $(@D)/page2.html
- path: css/buttondown.css
target: buttondown.css
targets:
- path: $(@D)/index.html
tool: pandoc
tool-settings:
number-sections: false
inputs:
- index.md
dependencies:
- .pansite.yaml
- path: $(@D)/page1.html
tool: pandoc
tool-settings:
number-sections: false
inputs:
- page1.md
dependencies:
- .pansite.yaml
- path: $(@D)/page2.html
tool: pandoc
tool-settings:
mathjax: true
inputs:
- page2.md
dependencies:
- .pansite.yaml
tool-settings:
pandoc:
number-sections: true
template-path: template.html
vars:
- [css, css/buttondown.css]
Each 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
Build it:
stack build
Run the example site:
cd _app/
stack exec -- pansite --port 3000
In your web browser, navigate to a route defined in .pansite.yaml, e.g. http://localhost:3000/page2.
Command-line options
$ 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
Available options:
-h,--help Show this help text
-p,--port PORT Port
-c,--config CONFIG Path to YAML application configuration file
-o,--output-dir OUTPUTDIR
Output directory
-v,--version Show version
Licence
Released under MIT License
Copyright © 2017—2018 Richard Cook
