Modding & Hacking
Faircamp offers a fair amount of customization through it settings: Native features that can be modularly enabled or disabled, the theming system, the possibility to integrate site-wide custom CSS and JS extensions.
Faircamp also makes certain trade-offs that guarantee that no matter what settings you pick, the results will almost always be highly accessible, predictable, stable and glitch free. This in turn imposes natural limits on what can and can't be customized.
Starting with 2.0, a new, for the time being experimental, approach for customization is available:
Programmatic access to the site tree (experimental)
Faircamp now provides a mechanism that allows you to hook directly into the raw output of its preprocessor. This gives you access to the intermediate site tree that Faircamp normally passes directly to its internal renderer.
This tree includes easily iterable lists of all artists, releases, etc. on your site, including the final inherited and resolved settings from your manifests, with references to all the media assets (audio, image, zip files) that Faircamp generated based on your settings.
To obtain the tree, go into your site directory and run faircamp with the
tree export <tree-file> command, providing a filename or path for the
JSON file that Faircamp should output:
faircamp tree export tree.json
Conversely, to pass this tree back to faircamp's internal renderer and have it
render a faircamp site based on its content, use the tree render <tree-file>
command:
faircamp tree render tree.json
The above implicitly builds to <site-dir>/.faircamp_build/ but you can
also explicitly state the build directory instead:
faircamp tree render tree.json --build-dir somewhere/else/check/carefully/
As always with the --build-dir option, check very carefully where you point
it – that directory gets wiped with each build!
Usecases for the site tree
The site tree can be used in very different ways. Here is a non-exhaustive set of possibilities:
- Tree transformations before rendering (easy and mostly harmless)
- Generate the tree
- Transform the JSON tree file by script or by hand
- Pass the transformed tree back to Faircamp for rendering
- More precise post-processing (varying levels of difficulty and trouble)
- Build the site as usual
- Generate the tree
- Pass the tree to a script that uses the tree data to precisely augment additions, deletions and/or modifications of certain files in the build directory
- Replacing the renderer (might turn into a multi-week side project)
- Generate the tree
- Pass the tree to a script (essentially: your own custom static site generator) that renders the site in a completely different way
- Replacing the preprocessor (veers into reverse-engineering territory)
- Generate a tree file from some faircamp site (only for reference)
- Now start from scratch without a faircamp site
- Manually generate a tree file (automation through a script highly recommended)
- Pass the tree to Faircamp for rendering
Usage considerations
Site tree access allows for powerful customization, but its usage can also result in partial or complete loss of other, less tangible perks of Faircamp: The reliability and accessibility inherent in HTML/CSS/JS that has hundreds of hours of design, development, auditing and testing in it. The time and energy Faircamp potentially saves you by being something that just works, that does not require you to re-implement all of this for yourself.
Which is to say, there are good reasons to use this, and good reasons not to, and it's advisable to deliberate those reasons for your own situation: How badly do I need these customizations compared to how much time it will probably take me to implement them? Will my changes preserve the accessibility provided by Faircamp's native renderer output? Do I have time to maintain my customizations in the future? Etc.
And to reiterate an important point: This feature is currently experimental. It's use and impact will be evaluated, and further direction adjusted based on what the real life findings around this are.