Skip to main content

Crate abbaye

Crate abbaye 

Source
Expand description

§Abbaye

logo

Abbaye is a Static Site Generator (SSG) for your software. As GitHub, Gitea, Forgejo and consorts offer, Abbaye can be used to generate a website with your software’s presentation, documentation, and distribution, per version.

Here’s an example file structure:

.
├── index.html # the main page of the website, enabling choosing a version, defaults to "latest" (contains a list of available versions and a iframe to the selected version?)
├── releases.feed # the RSS feed of the releases
├── repository/ # the directory containing the repository UI (if enabled in config)
├── repository.git # Clonable git repository
├── latest -> v2.0.0 # symlink to the latest version (biggest version number)
├── v1.0.0/ # the directory containing the version 1.0.0 of the software
│   ├── index.html # the main page of the version 1.0.0, from the README.md file.
│   │   # Contains a sidebar with links to the documentation and distribution.
│   │   # After the readme content, A changelog is displayed.
│   ├── docs/ # the directory containing the documentation of the version 1.0.0
│   │   ├── index.html # the main page of the documentation of the version 1.0.0
│   │   └── …
│   ├── docs.tar.gz # the tarball containing the documentation of the version 1.0.0
│   └── dist/ # the directory containing the distribution of the version 1.0.0
│       ├── source.tgz # the source code of the version 1.0.0
│       ├── mybin-v1.0.0-x86_64-unknown-linux-gnu
│       └── mybin-v1.0.0-x86_64-unknown-linux-musl
└── v2.0.0/ # the directory containing the version 2.0.0 of the software
    ├── index.html # the main page of the version 2.0.0
    ├── …
    └── …

§Why ?

This piece of software is for people that can’t or won’t use a full-featured forge such as GitHub, GitLab, ForgeJo & others. These forges provide “release pages” that allow you to upload and distribute your software, as well as get a changelog.

Abbaye is made to be a simple, lightweight alternative to these forges, for the release/documentation parts.

§Why “Abbaye” ?

Abbaye is a French word for Abbey. An Abbey is a type of monastery, on the big-ish side, but still a small, quiet place.

Anyway, that’s where you store and display your relics (your software releases).

§Installation

§Pre-built binaries

You can grab a pre-built binary from the releases page.

The -musl binaries are statically linked and should run everywhere, while the -gnu binaries are dynamically linked and require a compatible system library(which is probably available if you’re not using an exotic distribution).

§From source

To build from source, you need to have Rust installed. You can install Rust using rustup.

You can clone the repository and build the project using cargo build --release. The built binary will be located in target/release/abbaye. You can also install it directly using cargo install --path .

§Usage

Run abbaye init in your project’s directory to create a abbaye.toml configuration file. You can then customize the configuration to your liking. Here’s an example configuration file to get you started:

[site]
name = "Abbaye"
# required for Atom feed generation (canonical URLs are used for feed items)
base_url = "http://vit.am/~ololduck/abbaye/"

[version_extractor]
type = "git" # extract version from git tags
tag_prefix = "v"

[changelog] # use the default changelog parser (Keepachangelog format in CHANGELOG.md)

[[builders]]  # builds the project using cargo build --release
type = "cargo"
targets = ["x86_64-unknown-linux-gnu", "x86_64-unknown-linux-musl"]

[[builders]]  # generates documentation using cargo doc
type = "cargo_doc"
no_deps = true  # Don't include dependencies in the documentation

[[builders]]
# creates a compressed tarball of the source code (can be of anything, really)
type = "archive"

[[builders]]
# Just an example dumb script to showcase the `script` builder type
type = "script"
script = [
 "echo $ABBAYE_BUILDING_VERSION > .version",
]
outputs = [".version"]

Then run abbaye build to build the site. The site will be generated in the public/ directory by default. Now you can copy the contents of public/ to your web server to deploy the site. For instance, with rsync: rsync --progress -avz --links --perms --update public/ ololduck@vit.am:public_html/abbaye/

To have a look at all the available configuration options, please refer to the documentation of config::AbbayeConfig.

§A note on the repository UI

The repository UI is NOT enabled by default. It must be enabled explicitly in the configuration with the following:

[git_ui] # only this section is needed to enable the repository UI

It has multiple options (each presented with their defaults, if any):

[git_ui]
default_branch = "main"
max_commits = 200
repo_path = "."
clone_url = "{{ site.base_url }}/repository.git"

When the git UI is enabled, pages permitting browsing the tree of the repository are available, but only for the branches tips and the tags, as to not generate too much content. It already is quite a lot of content to generate for a simple repository UI (about 10MBs for Abbaye’s repository at the time of writing).

§✨ Customization ✨

You can dump the default theme/templates to your local filesystem with abbaye dump-theme.

This will create a .abbaye/theme/ directory in your current directory with the default templates, which you can then ✨customize✨.

If you don’t want to customize every template, simply delete the ones you don’t want to change.

In .abbaye/theme/static/, you will find the CSS sheet used by the default theme, across all templates. Editing this file will change the look and feel of all your site’s pages.

§Future plans

  • Add support for theming
  • Add support for more site variables, such as the site title, description, and author, or even a custom footer and stuff.
    • I added OpenGraph support, does that count?
  • Add support for a self-update-like command to update the abbaye binary to the latest version. The mechanisms put in place for this goal should be usable to any user of abbaye.

§Contributing

Contributions are welcome! As i am mainly a rust developer, i am open to any contributions that improve the project, especially to support more artifacts builders/types.

Just clone the repository and {send me an email,contact me on {IRC (ololduck@irc.libera.chat),the Fediverse (@ololduck@fosstodon.org)}} with {a link to your fork,a git patch,compliments and adoration}.

Modules§

builders
All builders for the site (ex: cargo build, cargo doc, etc.). Builder types, the [Builder] trait, and the parallel execution model.
changelog
Parses the changelog file and generates a changelog page for the site.
cli
Stuff related to the CLI interface. Also contains colour escape codes for terminal output.
config
Handles the abbaye.toml configuration file.
git_ui
Generates a static git web UI and clonable bare repository. Generates a static git repository web UI and a clonable bare clone.
site
Generates the site from the configuration and builds it.
updater 🔒
Self-update logic: fetches the release feed and replaces the binary when a newer version exists. Self-update logic for the abbaye self-update command.
version_extractors
Extracts current version information from different sources (ex: git tags, cargo metadata, etc.).

Functions§

build_all 🔒
Build the full website for every git tag, sorted from the lowest semver version to the highest.
main 🔒