Crate abbaye 

Abbaye

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
├── 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. If you don’t have rust installed, this project won’t be of much use to you, as it currently only implements rust builders :stuck_out_tongue:

You can clone the repository and build the project using cargo build --release.

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"
base_url = "http://vit.am/~ololduck/abbaye/" # required for Atom feed generation (canonical URLs are used for feed items)

[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]]
type = "archive"  # creates a compressed tarball of the source code (can be of anything, really)

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/

✨ 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✨.

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.
• 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.).

changelog

Parses the changelog file and generates a changelog page for the site.

cli 🔒

config

Handles the abbaye.toml configuration file.

site

Generates the site from the configuration and builds it.

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 🔒