← All versions Abbaye — 0.8.0

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.

CLI commands

CommandDescription
initCreate a new abbaye.toml file.
buildBuild the site. Use --repository-only to skip version pages and only rebuild the git UI.
build-allBuild the site for every git tag, from lowest to highest semver. Checks out each tag in order, builds, then restores HEAD.
dump-themeDump the default theme templates to .abbaye/theme/ (only templates for formats enabled in [site].formats).
dump-schemaPrint a JSON Schema for abbaye.toml to stdout (redirect to abbaye.schema.json for IDE autocompletion).
self-updateCheck for and install the latest release. Add --check to only check without downloading.

Configuration

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/"
# URL of the project's repository (shown on release pages)
repo_url = "https://git.sr.ht/~ololduck/abbaye"
# Output formats: "html", "gemtext", or both (default: ["html"])
formats = ["html", "gemtext"]
# Fediverse handle for social meta tags
fediverse_creator = "@ololduck@vit.am"

[site.opengraph]
image = "latest/logo.svg"
image_alt = "Abbaye logo"

[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"]
category = "Binaries"          # groups artifacts under this heading
name = "Pre-built binaries"    # optional display name on the release page
comment = "Built for Linux x86_64 (glibc and 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"
category = "Source"

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

Builders run concurrently by default. To enforce ordering, assign an id and reference it in depends_on:

[[builders]]
id = "compile"
type = "cargo"

[[builders]]
depends_on = ["compile"]
type = "script"
script = ["strip target/release/mybin"]
outputs = ["target/release/mybin"]

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"
# Glob patterns for refs to EXCLUDE from the UI (optional).
exclude = ["gh-pages", "tmp/*"]
# Glob patterns for refs to INCLUDE (optional, acts as an allowlist).
include = ["main", "v*"]

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 (only for the output formats enabled in [site].formats), 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

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@vit.am)} with {a link to your fork,a git patch,compliments and adoration}.

License: AGPL-3.0-or-later

Changes in 0.8.0

🚀 Features

🐛 Bug Fixes

🚜 Refactor

📚 Documentation

⚡ Performance

⚙️ Miscellaneous Tasks