#Cap

The builder is licensed under the CNPLv6 license or later, but not the written content (which is non-free, reserved rights).

Capsule is a simple to use website builder that's meant to be easy to use by default, but also made to have some useful tools for writers and publishers in order to make a simpler web.

This tool is meant to be an extension to Gemini capsules, whose structure is a plain directory structure of Gemtext .gmi files and various assets. A capsule is great, but making it compatible with HTTP too is even better.

This project's core is heavily inspired by the Zola static-site builder.

I started it as an alternative tool that is more tailored to my needs, after encountering a few more-or-less blocking frustrations with Zola. If you feel this tool is good for your needs, but not quite right to you, don't hesitate to check Zola out, it's great.

#Getting started

Cap's concept is that you can build a capsule (a personal website, in other words) with the defaults.

To start, you run the command cap init inside your capsule folder.

This will create a few defaults:

• /.cap.toml: Configuration file, enabling Cap to build this folder; merely having an empty file with this name is enough
• /.templates: The few default templates Cap needs to render itself; it also provides a good starting point for you to customize it
• /.gitignore: If the folder contains a .git folder (i.e. is a git repository), it will create a .gitignore containing an exclusion for the build folder. If a .gitignore file already exists, it will append this exclusion at the end instead.

The build folder lies at /.public from your base capsule folder. Its dotname is chosen to not be noise in the middle of your files when you edit it, and for some implementation reasons.

From this point, any time you want to get a new version of your capsule, you can run cap build to build a new copy of it, re-creating the /.public folder with the new content.

#Building your capsule

Running cap build will build your capsule into a /.public folder available at the root of your capsule, alongside the .cap.toml.

This /.public folder can be published however you want.

#Comparison with Zola

As stated above, this tool is directly inspired from how Zola works, as a creator.

What are the differences between both?

• External build scripts
  • Zola is a one-shot builder not including any "external buildscript" support
  • Cap has a configuration property made to provide an ordered list of commands you want to run after Cap has built the blog
  • The why: I have this need for my blog, because I have a post-build script that modifies every HTML file to set a custom theme value
• Gemini support
  • Zola is markdown-based, and doesn't have in its scopes to support Gemini
  • Cap supports Gemini out-of-the-box, and will, by default, copy gemini files (.gmi) into the output folder, so you can provide the build output through both HTTP and Gemini protocols
  • The why: I want to be able to build my capsules and other Gemini-supporting websites, and I also want to be able to write simple pages with the comfort of Gemtext

#Developer documentation

To compile Cap for a release, it is recommended to strip the debug symbols as well as append the build version.

$ go build -ldflags "-s -w -X main.BuildVersion=$(git describe --tags)" .

Right now, the tool's architecture, source-code, and internal decisions is underdocumented.

However, some features (the most recent ones) are talked in the POC folder of the documentation area.

It's a good start to try to grasp the most complex and obtuse parts of the system.

Additionally, a list of the remaining work to be done on the tool is available in the TODO document.