feat: a11y improvements and docs update (#12)

Author: EsseLowNitro

_config.yaml

@@ -9,4 +9,4 @@ defaults:
     values:
       layout: "page"
 
-excludes: "README.md"
+exclude: ["README.md"]

assets/main.css

@@ -19,17 +19,13 @@ body {
 
 a {
     color: #1a5fb4;
-    text-decoration: none;
+    text-decoration: underline;
 }
 
 a:visited {
     color: #613583;
 }
 
-a:hover {
-    text-decoration: underline;
-}
-
 h1 a, h1 a:visited, h2 a, h2 a:visited, h3 a, h3 a:visited, h4 a, h4 a:visited, h5 a, h5 a:visited, h6 a, h6 a:visited {
     color: #241f31;
 }
@@ -143,6 +139,10 @@ var {
     color: #76c9f6;
 }
 
+#site-menu ul li[aria-current]:hover a {
+    color: #aedff9;
+}
+
 #site-menu img {
     height: 1.8rem;
     width: 1.8rem;

content/CONTRIBUTING.md

@@ -8,11 +8,12 @@ permalink: /contributing
 
 All types of contributions are encouraged and valued. See the [Table of Contents](#table-of-contents) for different ways to help and details about how this project handles them. Please make sure to read the relevant section before making your contribution. It will make it a lot easier for us maintainers and smooth out the experience for all involved. The community looks forward to your contributions.
 
-> And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
-> - Star the project [in GitHub](https://github.com/secureblue/secureblue)
-> - Tweet about it
-> - Refer this project in your project's readme
-> - Mention the project at local meetups and tell your friends/colleagues
+And if you like the project, but just don't have time to contribute, that's fine. There are other easy ways to support the project and show your appreciation, which we would also be very happy about:
+
+- Star the project [in GitHub](https://github.com/secureblue/secureblue)
+- Tweet about it
+- Refer this project in your project's readme
+- Mention the project at local meetups and tell your friends/colleagues
 
 ## Table of Contents
 
@@ -34,15 +35,17 @@ to [email protected]
 
 ## I Have a Question
 
-> If you want to ask a question, opening a [GitHub issue](https://github.com/secureblue/secureblue) for it is preferred, but [Discord](https://discord.gg/qMTv5cKfbF) is available as well.
+If you want to ask a question, opening a [GitHub issue](https://github.com/secureblue/secureblue) for it is preferred, but [Discord](https://discord.gg/qMTv5cKfbF) is available as well.
 
 ## I Want To Contribute
 
-> ### Legal Notice
-> When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. 
+### Legal Notice
+
+When contributing to this project, you must agree that you have authored 100% of the content, that you have the necessary rights to the content and that the content you contribute may be provided under the project license. 
 
-> ### AI Content Policy
-> In the interest of accuracy, quality, and license of the project, contributing using AI generated code and content of any kind is forbidden.
+### AI Content Policy
+
+In the interest of accuracy, quality, and license of the project, contributing using AI generated code and content of any kind is forbidden.
 
 ### Reporting Bugs
 
@@ -143,7 +146,7 @@ Copy `/etc/containers/policy.json` to `~/.config/containers/policy.json` and the
 
 ### Making changes
 
-Configuration is stored in `recipes` folder in form of YAML files. Other files to be added to the image are stored in `files`. `common` holds pluggable modules to add to your custom image. `general` and `securecore` hold configs for the desktop and server images, respectively. Documentation for modules can be found [here](https://blue-build.org/learn/getting-started/).
+Configuration is stored in `recipes` folder in form of YAML files. Other files to be added to the image are stored in `files`. `common` holds pluggable modules to add to your custom image. `general` and `securecore` hold configs for the desktop and server images, respectively. Modules are detailed in [BlueBuild's documentation](https://blue-build.org/learn/getting-started/).
 
 ### Building
 
@@ -168,4 +171,4 @@ fix: remove broken confirmation message
 refactor: share logic between 4d3d3d3 and flarhgunnstow
 style: convert tabs to spaces
 test: ensure Tayne retains clothing
-```
+```

content/DONATE.md

@@ -4,6 +4,8 @@ description: "Donation options for secureblue"
 permalink: /donate
 ---
 
+# Donate
+
 All donations are appreciated. Sponsors get a role on the [Discord](https://discord.gg/qMTv5cKfbF) if desired. If you've donated but haven't yet been tagged with the role, please reach out to RoyalOughtness.
 
 There are multiple options available for donation:
@@ -14,24 +16,24 @@ There are multiple options available for donation:
 
 ## Bitcoin
 
-<img src="/assets/bitcoin.png" width=200 />
+<img alt="Bitcoin donation QR code" src="/assets/bitcoin.png" width=200 />
 
 `bc1qj4nxpfhsgj3f7w8c2689kq865apfla2jyxgaem`
 
 ## Monero
 
-<img src="/assets/monero.png" width=200 />
+<img alt="Monero donation QR code" src="/assets/monero.png" width=200 />
 
 `43fry9taGiwhAtNYEZNfssdzJ8Ra12ewAbQoVsvFzoLS6qMSgsE2FvE7xY52rAnKjPL5r2N88KYvqXpthUfSwa23K1BBMD9`
 
 ## Litecoin
 
-<img src="/assets/litecoin.png" width=200 />
+<img alt="Litecoin donation QR code" src="/assets/litecoin.png" width=200 />
 
 `ltc1q65hpetza8stgje640pcn25mef6xpdzxqazcawq`
 
 ## Ethereum
 
-<img src="/assets/ethereum.png" width=200 />
+<img alt="Ethereum donation QR code" src="/assets/ethereum.png" width=200 />
 
 `0x10289B51aEF109BBc07F68341F2Df8Ef60a5b618`

content/FAQ.md

@@ -6,7 +6,7 @@ permalink: /faq
 
 # FAQ
 
-Table of contents:
+## Table of contents:
 - [Why is Flatpak included? Should I use Flatpak?](#flatpak)
 - [Should I use Electron apps? Why don't they work well with hardened_malloc?](#electron)
 - [My fans are really loud, is this normal?](#fans)
@@ -22,7 +22,6 @@ Table of contents:
 - [Why doesn't my Xwayland app work?](#xwayland)
 - [Why I can't install nor use any GNOME user extensions?](#gnome-extensions)
 - [My clock is wrong and it's not getting automatically set. How do I fix this?](#clock)
-- [Why is DNS broken on my secureblue VM?](#vm-dns)
 - [How do I get notified of new releases?](#releases)
 - [Why don't my AppImages work?](#appimage)
 - [Why don't KDE Vaults work?](#kde-vaults)
@@ -34,38 +33,38 @@ Table of contents:
 - [Why don't extensions work in `hardened-chromium`?](#hardened-chromium-extensions)
 - [How do I customize secureblue?](#customization)
 
-#### Why is Flatpak included? Should I use Flatpak?
+### Why is Flatpak included? Should I use Flatpak?
 {: #flatpak}
 
 Consult our <a href="/articles/flatpak">Flatpak article</a>.
 
-#### Should I use Electron apps? Why don't they work well with hardened_malloc?
+### Should I use Electron apps? Why don't they work well with hardened_malloc?
 {: #electron}
 
 [https://github.com/secureblue/secureblue/issues/193#issuecomment-1953323680](https://github.com/secureblue/secureblue/issues/193#issuecomment-1953323680)
 
-#### My fans are really loud, is this normal?
+### My fans are really loud, is this normal?
 {: #fans}
 
 During rpm-ostree operations, it's normal. Outside of that, make sure you followed the NVIDIA steps in the [post-install instructions](/post-install#nvidia) if you're using an NVIDIA GPU.
 
-#### Should I use firejail?
+### Should I use firejail?
 {: #firejail}
 
 [No](https://madaidans-insecurities.github.io/linux.html#firejail), use ``bubblejail`` if there's no flatpak available for an app.
 
-#### An app I use won't start due to a malloc issue. How do I fix it?
+### An app I use won't start due to a malloc issue. How do I fix it?
 {: #standard-malloc}
 
 - For flatpaks, remove the `LD_PRELOAD` environment variable via Flatseal. To re-enable hardened_malloc for the respective flatpak, replace the removed variable.
 - For layered packages and packages installed via brew, run the application with `ujust with-standard-malloc APP`. This starts the app without hardened_malloc only once, it does not disable hardened_malloc for the app persistently.
 
-#### On secureblue half of my CPU cores are gone. Why is this?
+### On secureblue half of my CPU cores are gone. Why is this?
 {: #smt}
 
 `mitigations=auto,nosmt` is set on secureblue. This means that if your CPU is vulnerable to attacks that utilize [Simultaneous Multithreading](https://en.wikipedia.org/wiki/Simultaneous_multithreading), SMT will be disabled.
 
-#### How do I install software?
+### How do I install software?
 {: #software}
 
 1. Check if it's already installed using `rpm -qa | grep x`
@@ -75,19 +74,19 @@ During rpm-ostree operations, it's normal. Outside of that, make sure you follow
 
 Steam is an exception to the above.
 
-#### How do I install Steam?
+### How do I install Steam?
 {: #steam}
 
 ```
 ujust install-steam
 ```
 
-#### Another security project has a feature that's missing in secureblue, can you add it?
+### Another security project has a feature that's missing in secureblue, can you add it?
 {: #feature-request}
 
-First check [this](/#hardening) on whether it already lists an equivalent or better feature. If it doesn't, open a new [GitHub issue](https://github.com/secureblue/secureblue/issues).
+First check our [features list](/features) on whether it already lists an equivalent or better feature. If it doesn't, open a new [GitHub issue](https://github.com/secureblue/secureblue/issues).
 
-#### Why are bluetooth kernel modules disabled? How do I enable them?
+### Why are bluetooth kernel modules disabled? How do I enable them?
 {: #bluetooth}
 
 Bluetooth has a long and consistent history of security issues. However, if you still need it, run:
@@ -96,12 +95,12 @@ Bluetooth has a long and consistent history of security issues. However, if you
 ujust toggle-bluetooth-modules
 ```
 
-#### Why are upgrades so large?
+### Why are upgrades so large?
 {: #upgrade-size}
 
 This is an issue with rpm-ostree image-based systems generally, and not specific to secureblue. Ideally upgrades would come in the form of a zstd-compressed container diff, but it's not there yet. Check out [this upstream issue](https://github.com/coreos/rpm-ostree/issues/4012) for more information.
 
-#### Why can't I install new KDE themes?
+### Why can't I install new KDE themes?
 {: #ghns}
 
 The functionality that provides this, called GHNS, is disabled by default due to the risk posed by the installation of potentially damaging or malicious scripts. This has caused [real damage](https://blog.davidedmundson.co.uk/blog/kde-store-content/).
@@ -112,7 +111,7 @@ If you still want to enable this functionality, run:
 ujust toggle-ghns
 ```
 
-#### Why doesn't my Xwayland app work?
+### Why doesn't my Xwayland app work?
 {: #xwayland}
 
 Xwayland is disabled by default on GNOME, KDE Plasma, and Sway. If you need it, run:
@@ -121,7 +120,7 @@ Xwayland is disabled by default on GNOME, KDE Plasma, and Sway. If you need it,
 ujust toggle-xwayland
 ```
 
-#### Why I can't install nor use any GNOME user extensions?
+### Why I can't install nor use any GNOME user extensions?
 {: #gnome-extensions}
 
 This is because support for installing & using them has been intentionally disabled by default in secureblue.
@@ -133,26 +132,21 @@ To enable support for installing GNOME user extensions, you can run ujust comman
 ujust toggle-gnome-extensions
 ```
 
-#### My clock is wrong and it's not getting automatically set. How do I fix this?
+### My clock is wrong and it's not getting automatically set. How do I fix this?
 {: #clock}
 
 If your system time is off by an excessive amount due to rare conditions like a CMOS reset, your network will not connect. A one-time manual reset will fix this. This should never be required except under very rare circumstances.
 
 For more technical detail, see [#268](https://github.com/secureblue/secureblue/issues/268)
 
-#### Why is DNS broken on my secureblue VM?
-{: #vm-dns}
-
-The DNSSEC setting we set in `/etc/systemd/resolved.conf.d/securedns.conf` causes known issues with network connectivity when secureblue is used in a VM. To fix it, comment out `DNSSEC=allow-downgrade` in that file and manually set a dns provider in network settings.
-
-#### How do I get notified of new releases?
+### How do I get notified of new releases?
 {: #releases}
 
 To subscribe to release notifications, on the secureblue GitHub page, click "Watch", and then "Custom", and select Releases like so:
 
-![image](/assets/release-notifications.png)
+<img alt="GitHub screenshot" src="/assets/release-notifications.png" />
 
-#### Why don't my AppImages work?
+### Why don't my AppImages work?
 {: #appimage}
 
 AppImages depend on fuse2, which is unmaintained and depends on a suid root binary. For this reason, fuse2 support is removed by default. It's strongly recommended that you find alternative mechanisms to install your applications (flatpak, distrobox, etc). If you can't find an alternative and still need fuse2, you can add it back by layering something that depends on it.
@@ -163,19 +157,19 @@ For example:
 rpm-ostree install zfs-fuse
 ```
 
-#### Why don't KDE Vaults work?
+### Why don't KDE Vaults work?
 {: #kde-vaults}
 
 Similar to the AppImage FAQ, the KDE Vault default backend `cryfs` depends on fuse2. For this reason it's recommended that you migrate to an alternative that doesn't depend on fuse2, for example `fscrypt`. If you don't want to do so, you can add fuse2 back by layering something that depends on it, as described in the AppImage FAQ.
 
-#### How do I provision signed distroboxes?
+### How do I provision signed distroboxes?
 {: #distrobox-assemble}
 
 ```
 ujust distrobox-assemble
 ```
 
-#### Why aren't my apps loading on Nvidia Optimus?
+### Why aren't my apps loading on Nvidia Optimus?
 {: #nvidia-optimus}
 
 There is an [upstream bug](https://discussion.fedoraproject.org/t/gdk-message-error-71-protocol-error-dispatching-to-wayland-display/127927/21). You may need to run:
@@ -186,32 +180,32 @@ mkdir -p ~/.config/environment.d && echo "GSK_RENDERER=gl" >> ~/.config/environm
 
 This should no longer be required as of F41: https://discussion.fedoraproject.org/t/gdk-message-error-71-protocol-error-dispatching-to-wayland-display/127927/42
 
-#### Why won't `hardened-chromium` start?
+### Why won't `hardened-chromium` start?
 {: #hardened-chromium-start}
 
 Try starting `hardened-chromium` from the commandline by running `chromium-browser`. If you get an error about the current profile already running on another device, this is an issue with upstream chromium which can happen when you `rpm-ostree update` or `rpm-ostree rebase`. To fix this, simply run `rm ~/.config/chromium/SingletonLock`.
 
 `bubblejail` **SHOULD NOT** be used on `hardened-chromium`, there are issues reported with the pairing and removing the `bubblejail` config after it is applied can be difficult. It should also be noted that applying additional sandboxing may interfere with chromium's own internal sandbox, so it can end up reducing security.
 
-#### Why won't `hardened-chromium` start on Nvidia?
+### Why won't `hardened-chromium` start on Nvidia?
 {: #hardened-chromium-start-nvidia}
 
 On some Nvidia machines, `hardened-chromium` defaults to the X11 backend. Since secureblue disables Xwayland by default, this means that you will need to run `ujust toggle-xwayland` and reboot, for `hardened-chromium` to work.
 
-#### Why don't some websites that require JIT/WebAssembly work in `hardened-chromium` even with the V8 Optimizer toggle enabled?
+### Why don't some websites that require JIT/WebAssembly work in `hardened-chromium` even with the V8 Optimizer toggle enabled?
 {: #hardened-chromium-exceptions}
 
 This is an [upstream bug](https://issues.chromium.org/issues/373893056) that prevents V8 optimization settings from being applied to iframes embedded within a parent website. As a result, WebAssembly may not function on services that use a separate URL for their content delivery network or other included domains, such as VSCode Web ([https://github.dev](https://github.dev)). To make VSCode Web work properly, you need to manually allow V8 optimizations for the CDN by adding `https://[*.]vscode-cdn.net` to your list of trusted websites.
 
-#### Why don't extensions work in `hardened-chromium`?
+### Why don't extensions work in `hardened-chromium`?
 {: #hardened-chromium-extensions}
 
 Extensions in `hardened-chromium` are disabled by default, for security reasons it is not advised to use them. If you want content/ad blocking, that is already built into `hardened-chromium` and enabled by default. If you require extensions, you can re-enable them by disabling the `Disable Extensions` toggle under `chrome://settings/security`, then restart your browser (this toggle is per-profile).
 \
 \
 If the extension you installed doesn't work, it is likely because it requires WebAssembly (WASM) for some cryptographic library or some other optimizations (this is the case with the Bitwarden extension). To re-enable JavaScript JIT and WASM for extensions, enable the feature `chrome://flags/#internal-page-jit`.
 
-#### How do I customize secureblue?
+### How do I customize secureblue?
 {: #customization}
 
-If you want to add your own customizations on top of secureblue, you are advised strongly against forking. Instead, create a repo for your own image by using the [BlueBuild template](https://github.com/blue-build/template), then change your `base-image` to a secureblue image. This will allow you to apply your customizations to secureblue in a concise and maintainable way, without the need to constantly sync with upstream. For local development, [building locally](/contributing#building-locally) is the recommended approach.
+If you want to add your own customizations on top of secureblue, you are advised strongly against forking. Instead, create a repo for your own image by using the [BlueBuild template](https://github.com/blue-build/template), then change your `base-image` to a secureblue image. This will allow you to apply your customizations to secureblue in a concise and maintainable way, without the need to constantly sync with upstream. For local development, [building locally](/contributing#building-locally) is the recommended approach.