#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.
#Installing cap
It currently cannot be installed from the official rust package index because that package index cannot be used without an active github account which i don't have.
To install cap
you instead need to run the following (with the stable rust branch).
$ cargo install --git https://git.sr.ht/~artemis/cap
#Getting started
This currently isn't implemented in the tool redesign.
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.
This is implemented
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.
#Remaining TODOs
- Loaders
- [x] File loader
- [x] Feed loader
- [x] Page loader
- [ ] KDL loader
- Parsers
- [x] Gemini parser
- [x] Markdown parser
- [x] HTML parser
- [ ] GLS parser (using Pest for writing the parser? https://pest.rs)
- Preprocessor
- [ ] Pagination
- how the fuck am i supposed to implement this tho?
- like for index.html pages, do i just do like index.2.html or some bullshit like so? its ugly :<
- postponed bc not needed to get 1:1 ready for now (2024-11-01)
- Renderers
- [x] Page renderer
- [x] HTML template parsing
- [x] Feed renderer
- [x] File renderer
- [x] how the fuck am i gonna provide all the map/reduce/select/query features that are currently available and in use in Cap 0.4?
- [x] TBD if more intermediary types are needed
- Page index
- [x] Fetch index
- The fetch index registers all the leaves the parsers have produced, before allowing the renderers to do their work
- [ ] Link index
- The link index registers all the encountered links during page parsing, which may later be used to check for dead links
- Thumbnail compression
- [x] Thumbnail loading
- [x] Thumbnail support in page loading
- [x] Thumbnail rendering (imagemagick subprocess)
- [x] Imagemagick configuration / execution for pages' thumbnails
- [ ] Async support for rendering thumbnails
- no use for it now, we'll see when it'll become a bottleneck
- Metadata
- [ ] OpenMetrics generation of build stats
- [x] DOT leaf graph
- needs work to generate something "pretty" but is here
- ideally since it all starts with a single id and branches out, i'd like something circular
- twopi rendering looks nice for a pre-rendered version or an online js version
- Capsule core
- [x] Capsule config
- Init command
- [ ] Default templates, CSS, index.gmi, and config file creation
- Build command
- [x] Redirect pages rendering
- [x] Post-build command invocations
- Watch command
- [ ] Rebuild on inotify
- [ ] Partial rebuild support
- This requires to keep track of build dependencies through the ID/parent ID binding as well as through the query system the HTML/feed exposes to let the user build selector queries on what to include on their page
- [x] HTTP server
- [ ] Gemini server
- Clean stuff
- Markdown
- Syntax highlighting compatibility
- Core
- Split the main build megafunction
- Move the main build megafunction in its own thing at least please
#TODO: bugs
- A page's thumbnail cannot have an alt text
- thumbnail compression is implemented but disabled due to imagemagick's breaking changes in version 7+
- [Conf]: re-check conf fields to mark some optional (eg
base_url
which is not needed by default)
#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 capsule
- The why: I have this need for my capsule, 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