Skip to content

Commit e4ce1ea

Browse files
Stensel8Stensel8
committed
chore: major docs update, image migration, and site modernization
- Migrate Hextra theme from git submodule to Go module (go.mod/go.sum); remove .gitmodules entry - Replace supergfxctl with asusctl armoury throughout; supergfxctl is deprecated; GPU switching now handled via asusctl armoury set/get dgpu_disable - Add "Why CachyOS?" section and CachyOS Kernel Manager (scx_lavd / sched_ext) to getting-started - Add scx_lavd (sched_ext) CPU scheduler to system config table on homepage - Remove news page; content integrated into relevant pages - Expand known-issues: active issues, GPU/display bugs (PSR, amdgpu page faults), NVIDIA soft lockup, Brave crashes, YubiKey/FIDO2, GDM autologin, and VM troubleshooting - Add Smile emoji picker screenshots and documentation to applications - Add AVIF (quality 80, speed 6); document batch conversion in README - Update domain from zephyrus-linux.stentijhuis.nl to zephyrus-linux.stensel.nl in all files - Add contributor welcome message to CONTRIBUTING.md
1 parent bc9a4da commit e4ce1ea

57 files changed

Lines changed: 1517 additions & 1205 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitmodules‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +0,0 @@
1-
[submodule "themes/hextra"]
2-
path = themes/hextra
3-
url = https://github.com/imfing/hextra.git

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Contributing
22

3+
Also own a ROG Zephyrus device and are running Linux? And want to contribute or give opinions and/or tips? Issues and Pull Requests are welcome!
4+
5+
---
6+
37
## Commit messages
48

59
This project uses [Conventional Commits](https://www.conventionalcommits.org/).

‎LICENSE‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
MIT License
22

3-
Copyright (c) 2026 Sten Tijhuis
3+
Copyright (c) 2026 Stensel8
44

55
Permission is hereby granted, free of charge, to any person obtaining a copy
66
of this software and associated documentation files (the "Software"), to deal

‎README.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ English | [Nederlands](README.nl.md)
44

55
CachyOS on the ASUS ROG Zephyrus G16 GA605WV (2024). My personal setup log — documenting what worked, what didn't, and how I fixed it.
66

7-
**Browse the full documentation site: [zephyrus-linux.stentijhuis.nl](https://zephyrus-linux.stentijhuis.nl/)**
7+
**Browse the full documentation site: [zephyrus-linux.stensel.nl](https://zephyrus-linux.stensel.nl/)**
88

99

1010
## About this project
@@ -70,6 +70,27 @@ hugo --gc --minify
7070
The output is written to `./public/`. On push to `main`, GitHub Actions builds and deploys to GitHub Pages automatically.
7171

7272

73+
## Image assets
74+
75+
All images in this repository use the [AVIF](https://en.wikipedia.org/wiki/AVIF) format — open, royalty-free, and more efficient than PNG or JPEG at equivalent quality. AVIF is the modern standard for web images.
76+
77+
To convert PNG screenshots to AVIF, install `avifenc` from the `libavif` package:
78+
79+
```bash
80+
sudo pacman -S libavif
81+
```
82+
83+
Batch convert all PNGs in `static/images/` (converts and removes originals):
84+
85+
```bash
86+
cd static/images
87+
for f in *.png; do avifenc -q 80 -s 6 "$f" "${f%.png}.avif" && rm "$f"; done
88+
```
89+
90+
- `-q 80` — 80% quality (0–100 scale, 100 = lossless)
91+
- `-s 6` — encoder speed (0 = best compression, 10 = fastest)
92+
93+
7394
## Credits & resources
7495

7596
This project wouldn't exist without the work of these people and communities:

‎README.nl.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Nederlands | [English](README.md)
44

55
CachyOS op de ASUS ROG Zephyrus G16 GA605WV (2024). Mijn persoonlijke setup-log — wat werkte, wat niet, en hoe ik het heb opgelost.
66

7-
**Bekijk de volledige documentatiesite: [zephyrus-linux.stentijhuis.nl](https://zephyrus-linux.stentijhuis.nl/nl/)**
7+
**Bekijk de volledige documentatiesite: [zephyrus-linux.stensel.nl](https://zephyrus-linux.stensel.nl/nl/)**
88

99

1010
## Over dit project
@@ -69,6 +69,27 @@ hugo --gc --minify
6969
De output wordt geschreven naar `./public/`. Bij een push naar `main` bouwt GitHub Actions de site automatisch en deployt naar GitHub Pages.
7070

7171

72+
## Afbeeldingen
73+
74+
Alle afbeeldingen in deze repository gebruiken het [AVIF](https://nl.wikipedia.org/wiki/AVIF)-formaat — open, royaltyvrij en efficiënter dan PNG of JPEG bij vergelijkbare kwaliteit. AVIF is de moderne standaard voor webafbeeldingen.
75+
76+
Installeer `avifenc` uit het `libavif`-pakket om PNG-screenshots om te zetten naar AVIF:
77+
78+
```bash
79+
sudo pacman -S libavif
80+
```
81+
82+
Batch-conversie van alle PNGs in `static/images/` (converteert en verwijdert de originelen):
83+
84+
```bash
85+
cd static/images
86+
for f in *.png; do avifenc -q 80 -s 6 "$f" "${f%.png}.avif" && rm "$f"; done
87+
```
88+
89+
- `-q 80` — 80% kwaliteit (schaal 0–100, 100 = verliesvrij)
90+
- `-s 6` — encodersnelheid (0 = beste compressie, 10 = snelst)
91+
92+
7293
## Credits & bronnen
7394

7495
Dit project zou niet bestaan zonder het werk van deze mensen en communities:

‎content/_index.md‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,14 +28,6 @@ toc: false
2828
**Personal documentation.** I'm not a developer or Linux expert — just someone who switched to Linux on this laptop and figured things out along the way. I share what worked for me so others don't have to start from scratch. Everything here is at your own risk. Feel free to reach out if something doesn't work; I'm happy to think along. Running kernel 6.19.3-2 on CachyOS (Arch).
2929
{{< /callout >}}
3030

31-
## News
32-
33-
- **Moved to CachyOS** — settled on CachyOS as daily driver after testing multiple distros; best hardware support for the G16
34-
- **Kernel 7.0** — ASUS laptop quirks and AMDGPU enablement for RDNA 3.5; Radeon 890M expected ~20% uplift
35-
- **Kernel 6.19** — `asus-armoury` driver merged into mainline Linux; CachyOS 6.19.3-2 includes it
36-
37-
[Read all news →](/docs/news)
38-
3931
## Current System Configuration
4032

4133
| Component | Specification |
@@ -47,6 +39,7 @@ toc: false
4739
| **OS** | CachyOS (Arch) |
4840
| **Kernel** | 6.19.3-2 |
4941
| **Display Server** | Wayland (GNOME 49) |
42+
| **CPU Scheduler** | scx_lavd (sched_ext) |
5043
| **Secure Boot** | Enabled |
5144

5245
## Getting Started

‎content/_index.nl.md‎

Lines changed: 4 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -25,17 +25,9 @@ toc: false
2525
<div class="hx-mt-6"></div>
2626

2727
{{< callout type="info" >}}
28-
**Persoonlijke documentatie.** Ik ben geen developer of Linux-expert — gewoon iemand die overgestapt is naar Linux op deze laptop en dingen uitzoekende onderweg. Ik deel wat werkte zodat anderen niet helemaal opnieuw hoeven te beginnen. Alles is op eigen risico. Kom je ergens niet uit, laat het gerust weten — ik denk graag mee. Draait kernel 6.19.3-2 op CachyOS (Arch).
28+
**Persoonlijke documentatie.** Ik ben geen developer of Linux-expert — gewoon iemand die overgestapt is naar Linux op deze laptop en dingen uitzoekend onderweg. Ik deel wat werkte zodat anderen niet helemaal opnieuw hoeven te beginnen. Alles is op eigen risico. Kom je ergens niet uit, laat het gerust weten — ik denk graag mee. Draait kernel 6.19.3-2 op CachyOS (Arch).
2929
{{< /callout >}}
3030

31-
## Nieuws
32-
33-
- **Overgestapt naar CachyOS** — dagelijkse driver na het testen van meerdere distro's; beste hardware-ondersteuning voor de G16
34-
- **Kernel 7.0** — ASUS laptop quirks en AMDGPU-ondersteuning voor RDNA 3.5; Radeon 890M verwacht ~20% sneller
35-
- **Kernel 6.19** — `asus-armoury` driver gemerged in mainline Linux; CachyOS 6.19.3-2 bevat het al
36-
37-
[Bekijk al het nieuws →](/nl/docs/news)
38-
3931
## Huidige Systeemconfiguratie
4032

4133
| Onderdeel | Specificatie |
@@ -47,6 +39,7 @@ toc: false
4739
| **OS** | CachyOS (Arch) |
4840
| **Kernel** | 6.19.3-2 |
4941
| **Display Server** | Wayland (GNOME 49) |
42+
| **CPU Scheduler** | scx_lavd (sched_ext) |
5043
| **Secure Boot** | Ingeschakeld |
5144

5245
## Aan de slag
@@ -88,13 +81,13 @@ toc: false
8881
{{< hextra/feature-grid >}}
8982
{{< hextra/feature-card
9083
title="YubiKey 5C NFC"
91-
subtitle="FIDO2 LUKS poging en wat vandaag werkt"
84+
subtitle="FIDO2 LUKS-poging en wat vandaag werkt"
9285
icon="key"
9386
link="docs/security/yubikey"
9487
>}}
9588
{{< hextra/feature-card
9689
title="GDM Autologin"
97-
subtitle="GDM inlogscherm overslaan na LUKS ontgrendeling"
90+
subtitle="GDM-inlogscherm overslaan na LUKS-ontgrendeling"
9891
icon="lock-open"
9992
link="docs/security/autologin"
10093
>}}

‎content/docs/_index.md‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -98,17 +98,6 @@ Everything I've documented while running CachyOS on the ROG Zephyrus G16. Start
9898
>}}
9999
{{< /hextra/feature-grid >}}
100100
101-
## News
102-
103-
{{< hextra/feature-grid >}}
104-
{{< hextra/feature-card
105-
title="News"
106-
subtitle="CachyOS updates, kernel releases, and hardware-relevant changes"
107-
icon="rss"
108-
link="news"
109-
>}}
110-
{{< /hextra/feature-grid >}}
111-
112101
## Known Issues
113102

114103
{{< hextra/feature-grid >}}

‎content/docs/_index.nl.md‎

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -98,17 +98,6 @@ Alles wat ik heb opgeschreven tijdens het draaien van CachyOS op de ROG Zephyrus
9898
>}}
9999
{{< /hextra/feature-grid >}}
100100
101-
## Nieuws
102-
103-
{{< hextra/feature-grid >}}
104-
{{< hextra/feature-card
105-
title="Nieuws"
106-
subtitle="CachyOS updates, kernel releases en hardware-relevante wijzigingen"
107-
icon="rss"
108-
link="news"
109-
>}}
110-
{{< /hextra/feature-grid >}}
111-
112101
## Bekende Problemen
113102

114103
{{< hextra/feature-grid >}}

‎content/docs/applications.md‎

Lines changed: 79 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,28 @@ weight: 25
55

66
Everything I installed after the initial CachyOS setup. Organized loosely by category. Most of this is personal preference, but the Brave and libinput-config sections include non-obvious workarounds that aren't documented elsewhere.
77

8+
## Package sources
9+
10+
On CachyOS there are three places to get software from. When looking for an application, check them in this order:
11+
12+
1. **[CachyOS packages](https://packages.cachyos.org/)** — CachyOS's own repository, built on top of Arch. Packages here are optimized for modern CPUs (x86-64-v3/v4) and include CachyOS-specific patches. Install with `sudo pacman -S <package>`.
13+
14+
2. **[AUR](https://aur.archlinux.org/)** (Arch User Repository) — community-maintained build scripts for software not in the official repos. Install with an AUR helper like `paru -S <package>`. Quality varies per package but the AUR covers almost everything.
15+
16+
3. **[Flathub](https://flathub.org/)** — Flatpak packages that bundle all their own dependencies. Install with `flatpak install flathub <app-id>`, run with `flatpak run <app-id>`.
17+
18+
**Native (pacman/paru) vs Flatpak — which to choose?**
19+
20+
| | Native (pacman/paru) | Flatpak |
21+
|---|---|---|
22+
| **Performance** | Better — uses shared system libraries | Slightly worse — bundles own libraries |
23+
| **Integration** | Tight — full system access | Sandboxed — more isolated |
24+
| **Size** | Smaller | Larger |
25+
| **Compatibility** | Depends on distro | Consistent across distros |
26+
| **Security** | Standard | Better sandboxing |
27+
28+
Native packages offer better performance and system integration. Flatpaks trade some efficiency for compatibility and sandboxing. The choice is yours per application — both work fine on CachyOS.
29+
830
## Initial System Setup
931

1032
### Set the hostname
@@ -41,8 +63,19 @@ Coming from Windows, some things feel off without the right shortcuts. These are
4163
| # | Action | Command | Shortcut |
4264
|---|--------|---------|----------|
4365
| 5 | Open file manager | `nautilus` | `Super+E` |
66+
| 6 | Emoji picker | `flatpak run it.mijorus.smile` | Copilot key |
4467

45-
GNOME doesn't have a built-in shortcut for the file manager, so this one needs to be created manually.
68+
GNOME doesn't have built-in shortcuts for the file manager or an emoji picker, so these need to be created manually. See [Smile](#smile-emoji-picker) for how the Copilot key is used.
69+
70+
### GNOME window focus — apps opening in the background
71+
72+
Apps like Signal and Discord sometimes open in the background, showing a "Your app is ready" notification instead of bringing the window to the front. Fix this with:
73+
74+
```bash
75+
gsettings set org.gnome.desktop.wm.preferences focus-new-windows 'smart'
76+
```
77+
78+
The default `strict` mode never focuses new windows automatically. `smart` lets GNOME decide — in practice this means newly launched apps come to the foreground as expected.
4679

4780
### Touchpad scroll speed — no native GNOME setting (yet)
4881

@@ -102,78 +135,26 @@ sudo rm /etc/libinput.conf
102135

103136
### Brave
104137

105-
I use Brave as my main browser. I started with the Flatpak version but switched to the native package — the RPM version feels more native and offers better performance. There's a catch though: Brave 1.82+ has two crash bugs on GNOME Wayland that need workarounds before it's actually stable.
138+
I use Brave as my main browser. I started with the Flatpak version but switched to the native package — it integrates better with the system and offers better performance.
106139

107-
- **Native (pacman):** More native feel, better performance. This is what I use.
140+
- **Native (pacman):** Better system integration, better performance. This is what I use.
108141
- **Flatpak:** Might work better in some situations, but feels a bit more isolated.
109142

110143
**Installation**
111144

112-
{{< callout type="warning" >}}
113-
On CachyOS/Arch with GNOME + Wayland, Brave 1.82+ has two known crash bugs that require workarounds. The first is applied via the desktop entry; the second requires a setting in `brave://flags`.
114-
{{< /callout >}}
145+
[brave-bin on CachyOS packages](https://packages.cachyos.org/package/cachyos/x86_64/brave-bin) — available directly in the CachyOS repo, no AUR helper needed.
115146

116147
```bash
117148
sudo pacman -S brave-bin
118149
```
119150

120-
![Brave install instructions](/images/brave-install.avif)
121-
122-
**Workaround 1: patch the desktop entry**
123-
124-
Copy the system desktop entry to your user directory so it doesn't get overwritten by updates:
125-
```bash
126-
sudo cp /usr/share/applications/brave-browser.desktop ~/.local/share/applications/
127-
```
128-
129-
Patch all three `Exec=` lines with the flag:
130-
```bash
131-
sed -i \
132-
's|Exec=/usr/bin/brave-browser-stable %U|Exec=/usr/bin/brave-browser-stable --disable-features=WaylandWpColorManagerV1 %U|' \
133-
~/.local/share/applications/brave-browser.desktop
134-
135-
sed -i \
136-
's|Exec=/usr/bin/brave-browser-stable$|Exec=/usr/bin/brave-browser-stable --disable-features=WaylandWpColorManagerV1|' \
137-
~/.local/share/applications/brave-browser.desktop
138-
139-
sed -i \
140-
's|Exec=/usr/bin/brave-browser-stable --incognito$|Exec=/usr/bin/brave-browser-stable --incognito --disable-features=WaylandWpColorManagerV1|' \
141-
~/.local/share/applications/brave-browser.desktop
142-
```
143-
144-
Verify it worked — you should see exactly three `Exec=` lines:
145-
```bash
146-
grep "^Exec" ~/.local/share/applications/brave-browser.desktop
147-
```
148-
149-
**What this flag actually does (as far as I understand it):**
150-
151-
`--disable-features=WaylandWpColorManagerV1` — Brave 1.82+ introduced some Wayland color management extension that apparently conflicts with the AMD amdgpu driver on GNOME Wayland. Without this flag, Brave triggers GPU ring timeouts that crash the entire GNOME Shell session.
151+
![Brave official Linux install instructions](/images/brave-linux-install.avif)
152152

153-
**A note on `--ozone-platform=x11`:** I tried this flag as a workaround for a crash when opening or downloading Bitwarden attachments. It turned out to cause a worse problem: gnome-shell crashing with `SIGABRT` (`g_assertion_message_expr` in `meta_window_unmanage`), triggered during Picture-in-Picture video — the same underlying mutter crash documented in [gnome-mutter issue #4625](https://gitlab.gnome.org/GNOME/mutter/-/issues/4625). That takes down the entire desktop session and requires a hard reboot. The flag is gone. Brave now runs on native Wayland. The Bitwarden attachment crash still exists, but a Brave crash is preferable to losing the whole session.
154-
155-
**Workaround 2: disable hardware video decode in `brave://flags`**
156-
157-
{{< callout type="warning" >}}
158-
Hardware video decode still causes crashes even with the flag above. As long as the AMD VCN decoder is active, GNOME Shell crashes with SIGABRT — reproducible during Picture-in-Picture video. See [gnome-mutter issue #4625](https://gitlab.gnome.org/GNOME/mutter/-/issues/4625). Hardware video decode is **not yet stable** on the AMD Radeon 890M with GNOME Wayland.
159-
{{< /callout >}}
160-
161-
Go to `brave://flags` and disable:
162-
163-
- **Hardware-accelerated video decode** → `Disabled`
164-
165-
![Brave flags — hardware video decode disabled](/images/brave-flags.avif)
166-
167-
Video now decodes in software. After this, `brave://gpu` will show:
168-
169-
- `Video Decode: Software only. Hardware acceleration disabled`
170-
- `Video Encode: Software only. Hardware acceleration disabled`
171-
172-
![Brave hardware acceleration config](/images/brave-gpu-config.avif)
153+
Hardware acceleration works fine with current Brave and kernel versions. The crash bugs that affected Brave 1.82–1.86 are resolved — see [Known Issues]({{< relref "/docs/known-issues" >}}) for the history.
173154

174155
**Flatpak alternative**
175156

176-
If the native package gives you trouble:
157+
If the native package causes issues:
177158

178159
```bash
179160
flatpak install flathub com.brave.Browser
@@ -226,7 +207,7 @@ On kernel 6.18.x/6.19.x, VS Code hardware acceleration can trigger an amdgpu pag
226207
"disable-hardware-acceleration": true
227208
}
228209
```
229-
See the [NVIDIA Driver Installation Guide]({{< relref "/docs/hardware/nvidia-driver-installation" >}}) Known Issues section for details.
210+
See [Known Issues]({{< relref "/docs/known-issues" >}}) for details.
230211
{{< /callout >}}
231212

232213
### Kleopatra & GPG commit signing
@@ -343,6 +324,44 @@ For anything that doesn't work under Wine — like Microsoft 365 — I use a Win
343324

344325
![Bottles in the Flathub store](/images/bottles-flathub.avif)
345326

327+
### Smile — emoji picker
328+
329+
[Smile](https://mijorus.it/projects/smile) by Lorenzo Paderi is a simple emoji picker for Linux with custom tags support. Available on Flathub.
330+
331+
```bash
332+
flatpak install flathub it.mijorus.smile
333+
```
334+
335+
![Smile emoji picker in Flathub](/images/smile-flathub.avif)
336+
337+
**Settings**
338+
339+
Enable "Run in the background" and "Minimize on exit" in Smile's settings — this keeps the picker instant and dismisses it cleanly after selecting an emoji:
340+
341+
![Smile settings — run in background, minimize on exit](/images/smile-settings.avif)
342+
343+
**GNOME extension**
344+
345+
Install the [Smile complementary extension](https://extensions.gnome.org/extension/6096/smile-complementary-extension/) to enable automatic emoji pasting on Wayland. Without it, Smile can only copy to clipboard.
346+
347+
{{< callout type="warning" >}}
348+
In the Smile settings under "Paste emojis automatically", make sure the extension toggle is enabled after installing.
349+
{{< /callout >}}
350+
351+
**Keyboard shortcut — repurposing the Copilot key**
352+
353+
The Copilot key on the Zephyrus G16 is otherwise useless on Linux. GNOME registers it as `Shift+Super+TouchpadOff`. Repurpose it as an emoji picker shortcut:
354+
355+
Go to **Settings → Keyboard → Custom Shortcuts** and add:
356+
357+
- **Name:** Emoji picker
358+
- **Command:** `flatpak run it.mijorus.smile`
359+
- **Shortcut:** press the Copilot key
360+
361+
![Custom shortcuts list showing Emoji picker entry](/images/smile-custom-shortcuts.avif)
362+
363+
![Custom shortcut dialog for Smile — Copilot key binding](/images/smile-shortcut-dialog.avif)
364+
346365
### Solaar for Logitech devices
347366

348367
[Solaar](https://github.com/pwr-Solaar/Solaar) manages Logitech keyboards, mice, and other peripherals. Version 1.1.19 or newer.

0 commit comments

Comments
 (0)