at 8d154b4
# 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 ├── 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](https://en.wikipedia.org/wiki/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 ### Via mise If you use [mise](https://mise.jdx.dev), you can install abbaye via the included plugin: ```bash mise plugin install abbaye https://git.sr.ht/~ololduck/abbaye mise install abbaye ``` Or in your `mise.toml`: ```toml [tools] abbaye = "latest" [plugins] abbaye = "https://git.sr.ht/~ololduck/abbaye" ``` The plugin downloads pre-built binaries from the [releases page](http://vit.am/~ololduck/abbaye/latest) - no compilation needed. ### Pre-built binaries You can grab a pre-built binary from the [releases page](http://vit.am/~ololduck/abbaye/latest). 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](https://rustup.rs/). You can clone the [repository](https://git.sr.ht/~ololduck/abbaye) 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 | Command | Description | |---------|-------------| | `init` | Create a new `abbaye.toml` file. | | `build` | Build the site. Use `--repository-only` to skip version pages and only rebuild the git UI. | | `build-all` | Build the site for every git tag, from lowest to highest semver. Checks out each tag in order, builds, then restores HEAD. | | `dump-theme` | Dump the default theme templates to `.abbaye/theme/` (only templates for formats enabled in `[site].formats`). | | `dump-schema` | Print a JSON Schema for `abbaye.toml` to stdout (redirect to `abbaye.schema.json` for IDE autocompletion). | | `self-update` | Check for and install the latest release. Add `--check` to only check without downloading. | ## Configuration Here's an example configuration file to get you started: ```toml [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`: ```toml [[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: ```toml [git_ui] # only this section is needed to enable the repository UI ``` It has multiple options (each presented with their defaults, if any): ```toml [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 - [x] 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? - [x] Add support for a `self-update`-like command to update the abbaye binary to the latest version. ## 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