Refabricator
A Static Site Generator written in and for ReasonML.
Go right to the examples.
This project is Work In Progress and published to get early feedback from the community.
This project uses Esy to compile ReasonML to native.
Goals
Library and Binary
This project aims to provide a (pre-built) cli application - called refabricate.exe - covering the most common usecases as well as a library. This Library - called Refabricator - can be used to create a tailormade generator for more specific use-cases.
Extendability & Customizability
Extendability and customizability shall be focused on during development. Bot the library and binary shall stay versatile and easily adaptable to specific needs.
Proof of Concept
Currently work is done mostly on the Proof of concept milestone. Which means:
- a first version which demonstrates the value in having this application and library
- shipping a prebuilt binary with sane defaults for a site generator
- followin library featureset:
- read text of any local file
- read local md files and convert it to html
- resolve links in md to correct html ones
- read remote md files (git server / maybe also REST api?)
- write generated files to local filesystem
- write generated files to remote (maybe ftp?)
- provide rudimental way for templating
- following binary features:
- wrap all available library features in a nice CLI application
- provide sane defaults
- demonstrate usage and concepts of the library
Long term goals
On completion of the Proof of concept milestone some of the more relevant tasks are:
- Research on techniques to incorperate customizations to the binary without the need to recompile everything. (#24)
- Refabricate shall be adapted to also parse
*.reifiles. (#33) - performance improvements
Concepts
There is some vocabulary constantly used in naming and typing in this project. This nomenclation is explained in the following chapters in more detail.
Fabricator
A fabricator provides the ability to retrieve / generate data from some source. Some of them can be configured. (e.g. when having a fabricator which loads local files, the path can be configured)
One fabricator generates one or many fabrics.
Multiple Fabricators can be used along with each other.
Fabric
Fabric is the generic name for 'data in flight'. Using a fabricator to load some local markdown files will yield a markdown fabric for each file. Using a refabricator, these fabrics can be 'converted' to html fabrics.
Refabricator
A refabricator manipulates fabrics. It may 'transform' fabrics from one type to another.
A simple refabricator used for very simple templating is between, which takes a fabric and puts it in between of two other fabrics.
Factory
Subject to change
In the very first concepts a factory was meant to act like a 'sink'. For example a factory would write each fabric to a local file and would return the result type.
Currently it's not clear if special casing fabric => result really makes sense. This could also just be a refabricator.
Examples
md > between > log
Get all markdown files of a directory, put each content into a template and write everything out as log messages.
open Refabricator.Main;
let () =
fromMd("pages")
|> between((
"<html><head><title>Site generated with Refabricator</title></head><body><main>\n",
{|\n</main><footer>This site was generated by <a href="https://github.com/woeps/Refabricator">Refabricator</a>!</footer></body></html>|},
))
|> toLog;
2x md > between > files
Get all markdown files of one directory and put each content into a template + get all markdown files of another directory (without template) and write everything out as log messages.
open Refabricator.Main;
let () =
from([
fromMd("pages")
|> between((
"<html><head><title>Site generated with Refabricator</title></head><body><main>\n",
{|\n</main><footer>This site was generated by <a href="https://github.com/woeps/Refabricator">Refabricator</a>!</footer></body></html>|},
)),
fromMd("pages2"),
])
|> toFiles({path: "generated", extension: "html"});
// make sure your path/dir already exists
Usage
You need Esy, you can install the beta using npm:
% npm install -g esy@latest
NOTE: Make sure
esy --versionreturns at least0.5.4for this project to build.
Then run the esy command from this project root to install and build dependencies.
% esy
Now you can run your editor within the environment (which also includes merlin):
% esy $EDITOR
% esy vim
Alternatively you can try vim-reasonml which loads esy project environments automatically.
After you make some changes to source code, you can re-run project's build
again with the same simple esy command.
% esy
And test compiled executable (runs scripts.tests specified in
package.json):
% esy test