Fornax is a static site generator using type safe F# DSL to define page templates.
- Defining templates in F# DSL
- Creating pages using templates from
.md
files withlayout
entry - Creating plain pages without templates from
md
files withoutlayout
entry - Transforming
.less
files to.css
files - Transforming
.scss
files to.css
files (require havingsass
installed) - Coping other static content to output directory
- Defining
.css
styles using F# DSL - Handling site settings defined in multiple files (a la Jekyll's
_data
folder) (multiple models? unified model?)
You can install Fornax via the Scoop package manager on Windows
scoop bucket add fsharp-extras https://github.com/Krzysztof-Cieslak/scoop-fsharp-extras.git
scoop install fornax
You can install Fornax via the Homebrew package manager on OS X
brew tap Krzysztof-Cieslak/fornax && brew install fornax
You can install Fornax via the Linuxbrew package manager on Linux
brew tap Krzysztof-Cieslak/fornax && brew install fornax
You can download one of the releases found at https://gitlab.com/Krzysztof-Cieslak/Fornax/tags
Alternately you can clone the repo, build the source, and then move the files in your bin folder to a location of your choosing.
The main functionality of Fornax comes from CLI applications that lets user scaffold, and generate webpages.
fornax new
- scaffolds new blog in current working directory using really simple templatefornax build
- builds webpage, puts output to_public
folderfornax watch
- starts small webserver that host your blog post, and background process that recompiles blog whenver any changes are detected. That's suggested way of working with Fornaxfornax clean
- removes output directory and any temp files.fornax version
- prints out version of Fornaxfornax help
- prints out help
Fornax is using normal F# code (F# script files) to define templates and data types representing content, and yaml and Markdown to provide content (fitting defined models) for the templates. Sample webpage can be found in samples
folder - to build sample webpage run fornax build
in this folder.
Site settings are information passed to every page during generation - every template has access to this data.
The model representing site settings is defined in siteModel.fsx
file in the root folder of the webpage, content of settings is defined in _config.yml
file in the root folder of the webpage.
Sample siteModel.fsx
:
type SiteModel = {
SomeGlobalValue : string
}
Sample _config.yml
:
SomeGlobalValue: "Test global value"
Templates are F# script files representing different templates that can be used in the website. They need to #load
siteModel.fsx
file, and #r
Fornax.Core.dll
. They need to define F# record called Model
which defines additional settings passed to this particular template, and generate
function of following signature: SiteModel -> Model -> Post list -> string -> HtmlElement
. SiteModel
is type representing global settings of webpage, Model
is type representing settings for this template, Post list
contains simplifed information about all avaliable posts in the blog (usefull for navigation, creating tag cloud etc.) string
is main content of post (already compiled to html
).
Templates are defined using DSL defined in Html
module of Fornax.Core
.
All templates should be defined in templates
folder.
Sample template:
#r "../lib/Fornax.Core.dll"
#load "../siteModel.fsx"
open Html
open SiteModel
type Model = {
Name : string
Surname : string
}
let generate (siteModel : SiteModel) (mdl : Model) (posts: Post list) (content : string) =
html [] [
div [] [
span [] [ !! ("Hello world " + mdl.Name) ]
span [] [ !! content ]
span [] [ !! siteModel.SomeGlobalValue ]
]
]
Content files are .md
files containg page contnt, and header with settings (defined using yaml). Header part is parsed, and passed to template generate
function as Model
. Content part is compiled to html and also passed to generate
function. Header part needs to have layout
entry which defines which template will be used for the page.
Sample page:
---
layout: post
Name: Ja3
Surname: Ja4
---
# Something else
Some blog post written in Markdown
Templates are getting Post list
as one of the input parameter that can be used for navigation, creating tag clouds etc. The Post
is a record of following structure:
type Post = {
link : string
title: string
author: string option
published: System.DateTime option
tags: string list
content: string
}
It's filled based on respective entries in layout
part of the post content file. link
is using name of the file - it's usually something like \posts\post1.html
- Hmmm... it looks similar to Jekyll, doesn't it?
- Yes, indeed. But the main advantage over Jekyll is type safe DSL for defining templates, and fact it's using normal prorgramming language - no additional syntax to things like loops or conditional statements, it's also very easy to compose templates - you just
#load
other template and execute as normal F# function
- What about F# Formatting?
- F# Formatting is really good project, but it doesn't provide own rendering / templating engine - it's using Razor for that. Fornax right now is handling only rendering / templating - hopefully, it should work pretty well as rendering engine for F# Formatting.
Imposter syndrome disclaimer: I want your help. No really, I do.
There might be a little voice inside that tells you you're not ready; that you need to do one more tutorial, or learn another framework, or write a few more blog posts before you can help me with this project.
I assure you, that's not the case.
This project has some clear Contribution Guidelines and expectations that you can read here.
The contribution guidelines outline the process that you'll need to follow to get a patch merged. By making expectations and process explicit, I hope it will make it easier for you to contribute.
And you don't just have to write code. You can help out by writing documentation, tests, or even by giving feedback about this work. (And yes, that includes giving feedback about the contribution guidelines.)
Thank you for contributing!
The project is hosted on GitHub where you can report issues, fork the project and submit pull requests. Please read Contribution Guide
The library is available under MIT license, which allows modification and redistribution for both commercial and non-commercial purposes.