feat: add GitHub Pages docs site (Just the Docs), split packagechooser, disable IA upload

- docs/: new 13-page Jekyll site with Just the Docs theme
  - Home, Building, Installer, Packages, CI/CD, Development
  - Desktop Environments (with GNOME joke), Wallpapers, Launcher
  - Overlays, Root Overlay, Live Overlay
- .github/workflows/pages.yml: build & deploy docs from docs/ on
  push to master (only when docs/ changes)
- .github/workflows/build.yml: temporarily disable Internet Archive
  upload (if: false) until ISO is stable
- live-overlay/settings.conf: add instances section for init + desktop
  packagechooser instances
- live-overlay/modules/packagechooser_init.conf: init system selector
  (OpenRC, Runit, S6, Dinit) via netinstall-add method
- live-overlay/modules/packagechooser_desktop.conf: DE selector
  (Plasma, Xfce, Cinnamon, MATE, LXQt, i3, Sway, Hyprland + No Desktop)
  via legacy method
- README.md, AGENTS.md: fix sudo buildiso -> sudo ./buildiso, add note
  about system buildiso lacking --overwrite='*'
- .gitignore: add docs/_site/
This commit is contained in:
2026-06-29 21:27:46 +02:00
parent e3d35edcf7
commit 9fe5174cc7
22 changed files with 1124 additions and 4 deletions
+4
View File
@@ -0,0 +1,4 @@
source 'https://rubygems.org'
gem "jekyll", "~> 4.4.1"
gem "just-the-docs", "0.12.0"
+28
View File
@@ -0,0 +1,28 @@
title: Antergos NeXT
description: >-
A community revival of Antergos — Artix Linux, OpenRC, KDE Plasma, Calamares
theme: just-the-docs
color_scheme: dark
url: "https://antergos-next.github.io"
baseurl: "/antergos-iso"
aux_links:
"Antergos NeXT on GitHub":
- "https://github.com/Antergos-NeXT/antergos-iso"
aux_links_new_tab: true
heading_anchors: true
search_enabled: true
search:
heading_level: 3
previews: 3
back_to_top: true
back_to_top_text: "Back to top"
footer_content: "Copyright &copy; Antergos NeXT contributors. Distributed under the <a href=\"https://github.com/Antergos-NeXT/antergos-iso/blob/master/LICENSE\">GPL-3.0 License.</a>"
plugins:
- jekyll-seo-tag
+60
View File
@@ -0,0 +1,60 @@
---
title: Building
layout: default
nav_order: 2
---
# Building the ISO
Requires an **Artix-based** system with `artools` and `squashfs-tools`.
## Prerequisites
```bash
pacman -S artools squashfs-tools
modprobe loop
```
## Clone and configure
```bash
git clone https://github.com/Antergos-NeXT/antergos-iso.git
cd antergos-iso
export WORKSPACE_DIR="$PWD"
# Override pacman config with our repo (antergos-pkgs)
mkdir -p ~/.config/artools/pacman.conf.d
cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/
```
## Build
```bash
sudo -E ./buildiso -p antergos
```
> **⚠️ Use `./buildiso`, not `buildiso`.** The Artix system `/usr/bin/buildiso` lacks the `--overwrite='*'` flag, causing file conflicts between `calamares` and `calamares-branding-antergos-next` (both claim `/usr/share/calamares/branding/default/`). Our repo's `./buildiso` has it.
## Output
The ISO appears in `/var/lib/artools/buildiso/iso/antergos/`.
First build pulls ~5 GB from the internet. Subsequent builds use pacman cache. Go make a coffee. Or two. Maybe three.
## Environment variables
| Variable | Purpose |
|----------|---------|
| `WORKSPACE_DIR` | Must point to repo root. `buildiso` looks for profiles under `$WORKSPACE_DIR/iso-profiles/` |
| `COMPRESSION` | Squashfs compression type (e.g. `zstd`). If unset, `mksquashfs` fails silently with a zero-size image |
## Custom packages repo
The ISO pulls branding, Calamares config, and wallpapers from our custom repo. To use it on your system:
```ini
[antergos-pkgs]
SigLevel = Optional TrustAll
Server = https://antergos-next.github.io/antergos-packages
```
+43
View File
@@ -0,0 +1,43 @@
---
title: CI/CD
layout: default
nav_order: 5
---
# CI/CD Pipeline
Two GitHub Actions workflows:
## Build ISO (`build.yml`)
Triggers on push/PR to `master`. Runs in an `artixlinux/artixlinux:base` container.
Steps:
1. Install dependencies (artools, squashfs-tools, git, sudo, python)
2. Set `WORKSPACE_DIR` to the checkout path
3. Override pacman config with `[antergos-pkgs]` repo
4. Mount a 12 GB tmpfs at `/var/lib/artools/buildiso`
5. Run `./buildiso -p antergos`
6. Upload the ISO directory as a build artifact
### Internet Archive upload
Currently **disabled** (`if: false`) until ISO is stable. When enabled, uploads the built ISO to the Internet Archive with metadata:
- Collection: `open_source_software`
- Access keys: `IA_ACCESS_KEY`, `IA_SECRET_KEY` (repo secrets)
### Secrets
| Secret | Purpose |
|--------|---------|
| `IA_ACCESS_KEY` | Internet Archive S3 access key |
| `IA_SECRET_KEY` | Internet Archive S3 secret key |
## Deploy docs (`pages.yml`)
Triggers on push to `master` only when files under `docs/` change. Builds a Jekyll site from `docs/` using the Just the Docs theme and deploys to GitHub Pages.
## antergos-packages CI
Separate workflow in the [antergos-packages](https://github.com/Antergos-NeXT/antergos-packages) repo. Builds all packages listed in `packages.yaml` and publishes them to GitHub Pages as a pacman repo.
+94
View File
@@ -0,0 +1,94 @@
---
title: Desktop Environments
layout: default
nav_order: 7
---
# Desktop Environments
Available desktops in online mode, sourced from Artix repos.
## Plasma (KDE)
| | |
|---|---|
| **Repo** | world |
| **Group** | `plasma` |
| **Session** | `plasma.desktop` (Wayland) / `plasmax11.desktop` (X11) |
| **Notes** | Default DE. Wayland is the default session. `plasma-wayland-session` is NOT a separate package on Artix — it's bundled in `plasma-workspace` |
## Xfce
| | |
|---|---|
| **Repo** | galaxy |
| **Group** | `xfce4` |
| **Session** | `xfce.desktop` |
## Cinnamon
| | |
|---|---|
| **Repo** | galaxy |
| **Packages** | Individual (no meta-group) |
| **Session** | `cinnamon.desktop` |
## MATE
| | |
|---|---|
| **Repo** | galaxy |
| **Groups** | `mate` + `mate-extra` |
| **Session** | `mate.desktop` |
## LXQt
| | |
|---|---|
| **Repo** | galaxy |
| **Group** | `lxqt` |
| **Session** | `lxqt.desktop` |
## i3
| | |
|---|---|
| **Repo** | world |
| **Group** | `i3` |
| **Session** | `i3.desktop` |
## Sway
| | |
|---|---|
| **Repo** | world |
| **Packages** | `sway` + related |
| **Session** | `sway.desktop` |
## Hyprland
| | |
|---|---|
| **Repo** | world |
| **Packages** | `hyprland` |
| **Session** | `hyprland.desktop` |
## GNOME
| | |
|---|---|
| **Repo** | imaginary |
| **Group** | `gnome-systemd-hub` |
| **Session** | `does-not-exist.desktop` |
| **Status** | ❌ |
> You really think you can get GNOME here? GNOME deleted all other init support. Take a walk.
## Not available
- **Budgie** — not in any Artix repo (system, world, galaxy, lib32). Slideshow entries removed.
- **GNOME** — see above.
## No Desktop
Installs the base system only (TTY/login). Useful for servers or custom setups.
+86
View File
@@ -0,0 +1,86 @@
---
title: Development
layout: default
nav_order: 6
---
# Development
## Critical gotchas
### `./buildiso` vs `buildiso`
Always use the repo's `./buildiso`, **not** the system Artix `/usr/bin/buildiso`. The system version lacks `--overwrite='*'` and will fail with file conflicts between `calamares` and `calamares-branding-antergos-next`.
### `sudo -E` is required
Without `-E`, `WORKSPACE_DIR` is stripped and `load_profile()` returns empty `HAS_LIVE`/`LIVEUSER`, causing build failures.
### Pacman config must be user-overridden
`buildiso` reads from `~/.config/artools/pacman.conf.d/iso-x86_64.conf`. If missing, it falls back to the Artix default at `/usr/share/artools/pacman.conf.d/iso-x86_64.conf` which lacks `[antergos-pkgs]`.
```bash
mkdir -p ~/.config/artools/pacman.conf.d
cp pacman.conf.d/iso-x86_64.conf ~/.config/artools/pacman.conf.d/
```
### Squashfs compression
If `$COMPRESSION` is unset in config, `mksquashfs` produces a sparse zero file instead of a valid squashfs. Always verify compression is set, or remove stale images before retry.
### Calamares module precedence
`/etc/calamares/modules/` overrides `/usr/share/calamares/modules/`. Live-overlay online/offline directories override both.
### Live-overlay is not overlay-mounted
Live-overlay files are copied via `cp -LR` in `make_livefs()`. Deleting a file from live-overlay exposes the package version, not hides it. Use `NoDisplay=true` in `.desktop` files instead.
### `plasma-wayland-session` does not exist on Artix
Artix bundles the Wayland session into `plasma-workspace` itself. Do not add it to package lists.
### File conflicts
`calamares` and `calamares-branding-antergos-next` both install to `/usr/share/calamares/branding/default/`. Handled by `--overwrite='*'`.
### `calamares-next.sh SetConfig()`
Must `rm -f` the symlink at `/etc/calamares/settings.conf` before `cp`, otherwise `cp` follows the symlink and overwrites the offline config file instead of replacing it.
### Do not push commits while IA keys are set
Test ISOs manually first. IA credentials are set as repo secrets and will trigger an upload on push to master.
## Profile structure
```
iso-profiles/
├── antergos/
│ ├── profile.yaml # Packages, services (rootfs + livefs)
│ ├── root-overlay/ # Merged into squashfs rootfs
│ └── live-overlay/ # Merged into live environment
└── common/
└── common.yaml # Shared base packages
```
## Building locally
```bash
export WORKSPACE_DIR="$PWD"
sudo -E ./buildiso -p antergos
```
### A Note to the "Branding Police"
If you came here to hate and you're about to type "why are you using Antergos's branding" — pack your bags and go to **Manjaro**. We have Dustin's blessing. We are respectful. We are not them. Move on.
## Testing
Boot the resulting ISO in a VM. Verify:
- Wayland is the default display server (SDDM session is `plasma.desktop`)
- No "Install Artix Linux" entry in the app menu
- Wallpaper is set on first login
- Online mode: init selector + DE selector both work
- Slideshow renders correctly
+36
View File
@@ -0,0 +1,36 @@
---
title: Home
layout: home
nav_order: 1
---
# Antergos NeXT
> **Migration complete!** Antergos NeXT has migrated from systemd/Arch to OpenRC/Artix. Builds are stable, the installer works.
A community revival of Antergos — built on **Artix Linux** with **OpenRC**, **KDE Plasma**, and the **Calamares** installer (offline + online modes).
## Quick links
- [Building the ISO](building) — set up and build locally
- [Installer](installer) — Calamares modes, init & DE selectors
- [Custom packages](packages) — PKGBUILDs, repo setup
- [CI/CD](ci) — GitHub Actions pipeline
- [Development](development) — contributing, gotchas, conventions
## What changed
| Area | Original Antergos | Antergos NeXT |
|------|-------------------|---------------|
| Base | Arch Linux (systemd) | Artix Linux (OpenRC) |
| Desktop | GNOME | KDE Plasma |
| Installer | Custom Cnchi | Calamares |
| Build | archiso | artools (`buildiso`) |
## Sources
- [Artix Linux](https://artixlinux.org)
- [artools](https://gitea.artixlinux.org/artix/artools)
- [Calamares](https://codeberg.org/calamares/calamares)
- [antergos-packages](https://github.com/Antergos-NeXT/antergos-packages)
- [Original wallpapers](https://github.com/Antergos/wallpapers)
+60
View File
@@ -0,0 +1,60 @@
---
title: Installer
layout: default
nav_order: 3
---
# Calamares Installer
Uses [Calamares](https://codeberg.org/calamares/calamares) with two modes and custom branding.
## Modes
| Mode | Description |
|------|-------------|
| **Offline** | Unpacks a KDE Plasma squashfs — no internet needed |
| **Online** | Netinstall with init system choice + desktop selection |
The launcher (`calamares-next`) presents a mode picker before launching Calamares.
## Key differences from upstream
- `dracut`/`dracutlukscfg` replaced with `initcpiocfg`/`initcpio`/`luksopenswaphookcfg` (Artix uses mkinitcpio, not dracut)
- `services-openrc` module instead of `services-systemd`
- `removeuser` step removed, `postcfg` added
- `packagechooser` module compiled in (upstream skips it)
## Init system selector (online)
Users choose from: **OpenRC**, **Runit**, **S6**, **Dinit**.
Implemented as a `packagechooser` instance with `method: netinstall-add` — the selected init pulls its associated packages.
## Desktop selector (online)
Users choose from: **Plasma**, **Xfce**, **Cinnamon**, **MATE**, **LXQt**, **i3**, **Sway**, **Hyprland**, or **No Desktop**.
Implemented as a separate `packagechooser` instance with `method: legacy`. "No Desktop" installs only the base system (TTY-only).
## Available desktops
| Desktop | Artix Repo | Group/Packages |
|---------|------------|----------------|
| Plasma | world | `plasma` group |
| Xfce | galaxy | `xfce4` group |
| Cinnamon | galaxy | Individual packages |
| MATE | galaxy | `mate` + `mate-extra` groups |
| LXQt | galaxy | `lxqt` group |
| i3 | world | `i3` group |
| Sway | world | `sway` + related packages |
| Hyprland | world | `hyprland` |
> **Note:** Budgie is not available in any Artix repo and has been removed from all configs and slideshows.
## Offline mode
No packagechooser. Uses `unpackfs` to deploy a pre-built KDE Plasma squashfs, then `initcpiocfg` + `initcpio` for mkinitcpio configuration.
## Branding
Custom branding lives in the `calamares-branding-antergos-next` package, installed to `/etc/calamares/branding/default/`. The `componentName` in `branding.desc` must match its directory name.
+46
View File
@@ -0,0 +1,46 @@
---
title: Launcher
layout: default
nav_order: 9
---
# Calamares Launcher
The `calamares-next` script (`calamares-next.sh`) handles the installer boot flow.
## Flow
1. **Mode picker** — Dialog asking Offline or Online install
2. **Configuration** — Copies the appropriate `settings.conf` (offline or online) to `/etc/calamares/settings.conf`
3. **Launch** — Runs `calamares` with the selected config
## Launcher location
Installed by `calamares-branding-antergos-next` to `/usr/bin/calamares-next`.
## Desktop entry
`/usr/share/applications/calamares.desktop` in the live-overlay launches with:
```
Exec=sudo -E calamares-next
```
Note: `sudo -E` preserves environment variables (required for `WAYLAND_DISPLAY`, `XDG_CURRENT_DESKTOP`, etc. when launched from the SDDM session).
## Mode picker (dialog)
A simple `kdialog` or `zenity` dialog:
- **Offline** — No internet required, installs KDE Plasma from squashfs
- **Online** — Init system selector + DE selector via packagechooser, downloads packages from the internet
## Config switching
`SetConfig()` in `calamares-next.sh`:
1. Removes existing symlink at `/etc/calamares/settings.conf` (must `rm -f` first, not overwrite, or `cp` follows the symlink)
2. Copies the selected settings file
3. Calamares reads the config on launch
## Hiding "Install Artix"
The live-overlay includes `calamares-config-switcher.desktop` with `NoDisplay=true` — this hides the upstream Artix launcher while keeping the binary available.
+64
View File
@@ -0,0 +1,64 @@
---
title: Live Overlay
layout: default
parent: Overlays
nav_order: 2
---
# Live Overlay
Files in `iso-profiles/antergos/live-overlay/` exist only in the live environment — they are **not** present after installation.
## Contents
```
live-overlay/
├── etc/
│ ├── calamares/
│ │ ├── settings.conf # -> symlinks to online or offline
│ ├── calamares-offline/
│ │ ├── settings.conf # Offline install config (unpackfs)
│ │ └── modules/
│ │ └── ...
│ ├── calamares-online/
│ │ ├── settings.conf # Online install config (packagechooser)
│ │ └── modules/
│ │ ├── packagechooser_init.conf # Init system selector
│ │ ├── packagechooser_desktop.conf # DE selector
│ │ └── ...
│ └── sddm.conf.d/
│ └── kde_settings.conf # SDDM autologin + Wayland session
└── usr/
└── share/
└── applications/
├── calamares.desktop # Branded launcher
└── calamares-config-switcher.desktop # Hidden (NoDisplay=true)
```
## Key files
### `etc/calamares/settings.conf`
Symlink — points to either `../calamares-offline/settings.conf` or `../calamares-online/settings.conf`, set by `calamares-next.sh`.
### `etc/calamares-online/settings.conf`
Two `packagechooser` instances:
- `packagechooser@init` — init system (OpenRC, Runit, S6, Dinit) via netinstall-add
- `packagechooser@desktop` — DE selection via legacy method
### `etc/calamares-online/modules/packagechooser_init.conf`
Init selector config. Uses `method: netinstall-add` — the selected init pulls its associated packages.
### `etc/calamares-online/modules/packagechooser_desktop.conf`
DE selector config. Uses `method: legacy` — returns the selected DE as a global storage value.
### `etc/calamares-offline/settings.conf`
No packagechooser. Uses `unpackfs` to deploy a pre-built KDE Plasma squashfs.
### `usr/share/applications/calamares-config-switcher.desktop`
Has `NoDisplay=true` to hide it from the app menu. The upstream Artix "Install Artix Linux" entry is suppressed this way.
+51
View File
@@ -0,0 +1,51 @@
---
title: Root Overlay
layout: default
parent: Overlays
nav_order: 1
---
# Root Overlay
Files in `iso-profiles/antergos/root-overlay/` are merged into the root squashfs and become part of the installed system.
## Contents
```
root-overlay/
├── etc/
│ ├── os-release # Antergos NeXT branding
│ ├── pacman.conf # Includes [antergos-pkgs] repo
│ ├── sddm.conf.d/
│ │ └── kde_settings.conf # SDDM theme + Wayland session
│ └── skel/
│ └── .config/
│ └── autostart/
│ └── antergos-wallpaper.desktop # One-shot wallpaper setter
└── usr/
└── local/
└── bin/
└── set-antergos-wallpaper.sh # Wallpaper script
```
## Key files
### `etc/os-release`
Identifies the system as "Antergos NeXT" to tools, installers, and the login manager.
### `etc/pacman.conf`
Adds the `[antergos-pkgs]` custom repo so installed systems can receive updates.
### `etc/sddm.conf.d/kde_settings.conf`
Sets the SDDM session to `plasma.desktop` (Wayland) by default.
### `etc/skel/.config/autostart/antergos-wallpaper.desktop`
Runs the wallpaper setter on first login. Uses `X-KDE-autostart-phase=2` to run after Plasma has initialized.
### `usr/local/bin/set-antergos-wallpaper.sh`
Applies the wallpaper via `plasma-apply-wallpaperimage` and creates `~/.config/antergos-wallpaper-set` marker to prevent re-running.
+28
View File
@@ -0,0 +1,28 @@
---
title: Overlays
layout: default
nav_order: 10
has_children: true
---
# Overlays
Two directories under `iso-profiles/antergos/` control what goes into the ISO.
```
iso-profiles/antergos/
├── profile.yaml
├── root-overlay/ # → rootfs (squashfs)
└── live-overlay/ # → live environment (initramfs)
```
## How overlays work
- `root-overlay/` files are merged into the root squashfs — they become part of the installed system
- `live-overlay/` files are copied into the live environment only — they're not present after installation
- Overlays are **self-contained** (no symlinks to external directories) so the repo builds standalone
- Live-overlay files are **copied** via `cp -LR` in `make_livefs()`, not overlay-mounted. Deleting a file from live-overlay exposes the package version underneath
> **Disclaimer:** No symlinks were harmed in the making of this ISO. Well, maybe a few. We killed some.
> Also: this ISO is 100% systemd-free. Not even a trace. We checked. Twice.
+58
View File
@@ -0,0 +1,58 @@
---
title: Packages
layout: default
nav_order: 4
---
# Custom Packages
Custom PKGBUILDs live in the [antergos-packages](https://github.com/Antergos-NeXT/antergos-packages) repo.
## Package list
| Package | Purpose |
|---------|---------|
| `calamares` | Built with `packagechooser` module enabled, `dracut`/`initramfs` modules skipped |
| `calamares-branding-antergos-next` | Branding files: `branding.desc`, `show.qml`, `settings.conf`, `packagechooser.conf`, `initcpiocfg.conf`, `initcpio.conf`, `calamares-next.sh` |
| `antergos-wallpapers` | Default wallpapers installed to `/usr/share/wallpapers/` (KDE) and `/usr/share/backgrounds/` (other DEs) |
| `linux-next` | Custom kernel based on `linux-artix` |
| `winver` | "About Antergos NeXT" dialog built with KF6 + Qt6 |
## Repo setup
```ini
[antergos-pkgs]
SigLevel = Optional TrustAll
Server = https://antergos-next.github.io/antergos-packages
```
## Build system
Packages are built and published via CI. The build order is defined in `packages.yaml`. AUR packages (`yay`, `downgrade`) are included with retry logic for transient clone failures.
## Index
The package index (`index.db`, `index.files`) is generated with timestamps in **Europe/Berlin** timezone. See `generate-index.py`.
## PKGBUILD notes
### calamares
- `_skip_modules` includes `dracut`, `initramfs`, `initramfscfg` — these are Artix/systemd-holdovers not needed on OpenRC/mkinitcpio
- `-DCMAKE_DISTRIBUTION_NAME` is a **no-op** — Calamares ignores it. The "for <distro>" text comes from `versionedName` in the active branding component at runtime
### calamares-branding-antergos-next
- `packagechooser.conf` provides a DE-only fallback for standalone use
- `settings_offline.conf` / `settings_online.conf` override live-overlay settings at install time
- `calamares-next.sh` `SetConfig()` must remove the symlink before copying config, or it follows the link and overwrites the wrong file
### antergos-wallpapers
- Installs to `/usr/share/wallpapers/antergos-wallpaper/` with `metadata.desktop` for KDE picker support
- Also available at `/usr/share/backgrounds/antergos/` for other DEs
- Current wallpaper: GNOME Adwaita Morning (`adwaita-morning.webp`, CC BY-SA 3.0 by Jakub Steiner)
## File conflict notes
`calamares` and `calamares-branding-antergos-next` both claim `/usr/share/calamares/branding/default/branding.desc` and `show.qml`. Resolved at ISO build time via `--overwrite='*'` in repo's `./buildiso`.
+46
View File
@@ -0,0 +1,46 @@
---
title: Wallpapers
layout: default
nav_order: 8
---
# Wallpapers
The `antergos-wallpapers` package provides default wallpapers for the live session and installed system.
## Current wallpaper
GNOME **Adwaita Morning** (`adwaita-morning.webp`) — 7680×4320, CC BY-SA 3.0 by Jakub Steiner / GNOME Project.
## Installation paths
| Path | Purpose |
|------|---------|
| `/usr/share/wallpapers/antergos-wallpaper/` | KDE wallpaper picker (requires `metadata.desktop`) |
| `/usr/share/backgrounds/antergos/` | Other DEs / fallback |
## How it appears in KDE
KDE's wallpaper picker scans `/usr/share/wallpapers/` for directories containing a `metadata.desktop` file. The `metadata.desktop` format:
```ini
[Wallpaper]
name=Antergos NeXT
filename=adwaita-morning.webp
```
## Set on first login
Since Plasma overwrites `/etc/skel/.config/plasma-org.kde.plasma.desktop-appletsrc` on first login, the wallpaper is applied via a one-shot autostart script:
1. `/usr/local/bin/set-antergos-wallpaper.sh` — runs `plasma-apply-wallpaperimage`, creates marker file `~/.config/antergos-wallpaper-set`
2. `~/.config/autostart/antergos-wallpaper.desktop` — calls the script with `X-KDE-autostart-phase=2`
The marker file prevents the script from running on subsequent logins.
## Customizing
To replace the wallpaper, update:
- `packages/antergos-wallpapers/PKGBUILD` (source + checksum)
- `packages/antergos-wallpapers/adwaita-morning.webp`
- `packages/antergos-wallpapers/metadata.desktop` (if changing name)