From 6c12033462e38d800adb0a97ff227a86e7296836 Mon Sep 17 00:00:00 2001 From: clsty Date: Sat, 10 Feb 2024 00:27:15 +0800 Subject: [PATCH] Update docs. --- .../{00description.md => 00.description.md} | 0 .../docs/en/i-i/{01setup.md => 01.setup.md} | 45 +++++++---- src/content/docs/en/i-i/02.usage.md | 75 +++++++++++++++++++ src/content/docs/en/i-i/02usage.md | 34 --------- src/content/docs/en/i-i/03.troubleshooting.md | 63 ++++++++++++++++ src/content/docs/en/i-i/03troubleshooting.md | 8 -- .../docs/en/i-i/{04faq.md => 04.faq.md} | 0 src/content/docs/en/index.mdx | 26 +++---- 8 files changed, 181 insertions(+), 70 deletions(-) rename src/content/docs/en/i-i/{00description.md => 00.description.md} (100%) rename src/content/docs/en/i-i/{01setup.md => 01.setup.md} (50%) create mode 100644 src/content/docs/en/i-i/02.usage.md delete mode 100644 src/content/docs/en/i-i/02usage.md create mode 100644 src/content/docs/en/i-i/03.troubleshooting.md delete mode 100644 src/content/docs/en/i-i/03troubleshooting.md rename src/content/docs/en/i-i/{04faq.md => 04.faq.md} (100%) diff --git a/src/content/docs/en/i-i/00description.md b/src/content/docs/en/i-i/00.description.md similarity index 100% rename from src/content/docs/en/i-i/00description.md rename to src/content/docs/en/i-i/00.description.md diff --git a/src/content/docs/en/i-i/01setup.md b/src/content/docs/en/i-i/01.setup.md similarity index 50% rename from src/content/docs/en/i-i/01setup.md rename to src/content/docs/en/i-i/01.setup.md index dcbe317..d90d440 100644 --- a/src/content/docs/en/i-i/01setup.md +++ b/src/content/docs/en/i-i/01.setup.md @@ -3,23 +3,25 @@ title: Installation layout: /src/layouts/autonum.astro --- -**NOTE**: Below process only provides user-level customization and is NOT a complete solution for a fresh install. You have to set up network, bluetooth, nvidia stuff, etc. yourself +# Installation +## NOTEs +1. Below process only provides user-level customization and is NOT a complete solution for a fresh install. You have to set up network, bluetooth, nvidia stuff, etc. yourself +2. The author personally use (and highly recommend) EndeavourOS GNOME to not have to deal with all that hassle. Though you can use regular Arch just fine. It's never necessary to reinstall your system for this! +3. If your distro isn't Arch(-based), you'll have to figure out the equivalents of packages below. +4. If you only have 8Gb of ram, you might wanna [set up zram](https://forum.endeavouros.com/t/enabling-zram-in-endeavouros/37746) (or swap) before starting the installation, since compiling Hyprland takes quite a bit of resources. -** - I personally use (and highly recommend) EndeavourOS GNOME to not have to deal with all that hassle. Though you can use regular Arch just fine. **It's never necessary to reinstall your system for this!** If your distro isn't Arch(-based), you'll have to figure out the equivalents of packages below +## Automated installation (Arch distros only) +Clone, checkout this branch, then run install script: +```bash +cd ~/Downloads # Let's not trash your home folder +git clone https://github.com/end-4/dots-hyprland.git +cd dots-hyprland && git checkout illogical-impulse +./install.sh +``` -> [!TIP] -> If you only have 8Gb of ram like me, you might wanna [set up zram](https://forum.endeavouros.com/t/enabling-zram-in-endeavouros/37746) (or swap) before starting the installation, since compiling Hyprland takes quite a bit of resources +This script is idempotent, which means that you can run it multiple times. -# Automated installation (Arch distros only) -- Clone, checkout this branch, then run install script: - ```bash - cd ~/Downloads # Let's not trash your home folder - git clone https://github.com/end-4/dots-hyprland.git - cd dots-hyprland && git checkout illogical-impulse - ./install.sh - ``` - -# Manual installation +## Manual installation - Get packages and add user to `video` and `input` group ```bash yay -S blueberry brightnessctl cliphist coreutils curl fish foot fuzzel gjs gnome-bluetooth-3.0 gnome-control-center gnome-keyring gobject-introspection grim gtk3 gtk-layer-shell libdbusmenu-gtk3 meson networkmanager npm plasma-browser-integration playerctl polkit-gnome python-pywal ripgrep sassc slurp starship swayidle typescript upower xorg-xrandr webp-pixbuf-loader wget wireplumber wl-clipboard tesseract yad ydotool adw-gtk3-git cava gojq gradience-git hyprland-git hyprpicker-git lexend-fonts-git python-material-color-utilities python-pywal python-poetry python-build python-pillow ttf-material-symbols-variable-git ttf-space-mono-nerd swaylock-effects-git ttf-jetbrains-mono-nerd wayland-idle-inhibitor-git wlogout wlsunset-git @@ -51,3 +53,18 @@ layout: /src/layouts/autonum.astro - If you want media thumbnail from your browser to be shown, get the "Plasma browser integration" extension - For [Chromium](https://chrome.google.com/webstore/detail/plasma-integration/cimiefiiaegbelhefglklhhakcgmhkai) - For [Firefox](https://addons.mozilla.org/en-US/firefox/addon/plasma-integration/) + +# Uninstallation +Currently, there's a script for uninstallation, but it's far from perfect and is not actively maintained. + +> The point is that this repo is not a typical "software", but a set of config, +> Therefore it's very hard to make a proper uninstallation script, +> which should revert all changes made by the installation script. +> +> For example, the installation script will install `yay` (AUR-helper) for you if you don't have one. +> However, what should the uninstallation script do to revert this changes? +> - Remove `yay` or `yay-bin`? Not proper, because you may already have one of them installed by yourself (NOT by the installation script). +> - Even if the installation script had logged the package list installed by the script, it's still not proper to remove `yay` or `yay-bin` when the log showed `yay` or `yay-bin` is installed by the script, because you may have other programs using `yay` and this removal will break their functions. +> +> In conclusion, it's nearly not possible to write a proper uninstallation script. +> You'd better make reverted changes manually as you need. diff --git a/src/content/docs/en/i-i/02.usage.md b/src/content/docs/en/i-i/02.usage.md new file mode 100644 index 0000000..df60f4f --- /dev/null +++ b/src/content/docs/en/i-i/02.usage.md @@ -0,0 +1,75 @@ +--- +title: Usage +layout: /src/layouts/autonum.astro +--- + +# General +- For a list of keybinds, hit `Super`+`/` +- just play around with it a bit and click everywhere ;) this just documents some non-obvious stuff + +# Overview/launcher +Press `Super` to open. + +- **Windows** + - Drag to move them to different workspaces + - Right-click for a few options +- **Search** + - Calculation: Type something starting with a number + - Commands: They'll be detected and shown to you if you type in. + - Performs a headless execution by default + - If the command starts with sudo, it'll be launched in `foot` terminal. + - Directory search: Type a directory starting with `~` or `/`. + - Subdirectories will be shown if the path is correct. Activating opens folder/file + - Hit enter directly on the entry to open the typed folder/file + - Actions: An actions starts with `>`. See the keybind cheatsheet for a list of actions + - Apps by default, of course! + +# Bar controls +- Media: + - Top-right corner + - Middle-click to play/pause media, Right-click for next track + - Scroll to change volume + - Click the music pill for a controls window +- Brightness: Scroll top-left corner +- Launcher: Middle-click workspace widget +- Virtual keyboard: Right-click workspace widget + +# Misc +## How to resize | set resolution | font size +Reference: + +You can use gsettings to change the font size, like this: +```bash +gsettings set org.gnome.desktop.interface font-name 'Rubik 9' +``` +Rubik here is the font name and 9 is the font size in pt (1pt = 1.3333 px) + +Stuff should scale according to the font size. Some ags element may need a restart of ags to take effect. + +If some elements are wayy too big, then it's possible that css totally not working, see . + +## How to change time format +Reference: + +**NOTE**: You may need to run `man date` for time format. + +For AGS bar (it's not a dock bar I guess), you should edit `~/.config/ags/widgets/bar/system.js`. +Find `"%H:%M"` there and change it to what you like. +Its format may refer to [this page](https://docs.gtk.org/glib/method.DateTime.format.html). + +The lockscreen is swaylock currently. Edit its config in `~/.config/swaylock/config` to suit your needs. +For time format you need to adjust `timestr`. + +## How to copy text in notification +Reference: + +Click and hold a notification for a while, and its content will be copied. + +## How to set city for weather +Reference: + + +The value will be used as `${city}` for `curl https://wttr.in/lujiang${city}?format=j1`. + +By default the value comes from `curl ipinfo.io`. +You can also manually set the value by setting the env var `$AGS_WEATHER_CITY`. diff --git a/src/content/docs/en/i-i/02usage.md b/src/content/docs/en/i-i/02usage.md deleted file mode 100644 index 7fce04b..0000000 --- a/src/content/docs/en/i-i/02usage.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Usage -layout: /src/layouts/autonum.astro ---- - -- For a list of keybinds, hit `Super`+`/` -- just play around with it a bit and click everywhere ;) this just documents some non-obvious stuff - ---- -- Overview/launcher [ press `Super` to open ] - - **Windows** - - Drag to move them to different workspaces - - Right-click for a few options - - **Search** - - Calculation: Type something starting with a number - - Commands: They'll be detected and shown to you if you type in. - - Performs a headless execution by default - - If the command starts with sudo, it'll be launched in `foot` terminal. - - Directory search: Type a directory starting with `~` or `/`. - - Subdirectories will be shown if the path is correct. Activating opens folder/file - - Hit enter directly on the entry to open the typed folder/file - - Actions: An actions starts with `>`. See the keybind cheatsheet for a list of actions - - Apps by default, of course! - ---- -- **Bar controls:** - - Media: - - Top-right corner - - Middle-click to play/pause media, Right-click for next track - - Scroll to change volume - - Click the music pill for a controls window - - Brightness: Scroll top-left corner - - Launcher: Middle-click workspace widget - - Virtual keyboard: Right-click workspace widget diff --git a/src/content/docs/en/i-i/03.troubleshooting.md b/src/content/docs/en/i-i/03.troubleshooting.md new file mode 100644 index 0000000..ebb287c --- /dev/null +++ b/src/content/docs/en/i-i/03.troubleshooting.md @@ -0,0 +1,63 @@ +--- +title: Steps for troubleshooting +layout: /src/layouts/autonum.astro +--- + +# Hints + +The bar, and the side bars, cheatsheet, etc. belongs to AGS. + +To restart AGS and see its debug info, you may need to run this in terminal (by default press `Super+T` to open one): +```bash +pkill ags;ags +``` +And see if there're any errors, CRITICALs and WARNINGs. + +> Use some common sense. If you can't figure out, open an issue/discussion and we'll try to help. + +# Troubleshooting list + +## The player panel does not pop up when there is media playing +> Reference: [end-4/dots-hyprland#168](https://github.com/end-4/dots-hyprland/issues/168) + +Your player must have mpris support (see supported client [here](https://wiki.archlinux.org/title/MPRIS)). + +If you are using firefox as player, Plasma Integration extension should be installed and enabled for firefox, and the package `plasma-browser-integration` should be installed on Arch Linux. + +Then, when firefox is playing media, the following command: +```bash +dbus-send --print-reply --dest=org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus.ListNames|grep mpris +``` +should at least return +```plain +string "org.mpris.MediaPlayer2.plasma-browser-integration" +``` +note that output like `string "org.mpris.MediaPlayer2.firefox.instance_1_37"` does NOT work. + +If for some reason, firefox still does not have dbus `org.mpris.MediaPlayer2.plasma-browser-integration` showing up, +consider the following steps: +1. Create a new profile using `firefox --ProfileManager`. +2. Launch firefox with the newprofile and install the Plasma Integration extension again. +3. Restart firefox with the new profile and try again. + +Note: `playerctl -F metadata` may also be helpful for debugging. +## Firefox sometimes crashes +When this happens, please use `(xWayland) Firefox`, which desktop file is provided in `~/.local/share/applications` with `env MOZ_ENABLE_WAYLAND=0` for `Exec` entry. + +This is just a workround, which makes Firefox running under xWayland. + +## ags installation failed +### `PermissionError: [Errno 13] Permission denied: '/usr/local/lib/libgvc.so'` +Run: +```bash +pacman -Qo /usr/local/lib/libgvc.so +``` +to check whether this file belongs to any package (very likely not, because it's inside `/usr/local`). + +If not, then it's probably safe to just remove it. If you're sure about that, run this: +```bash +sudo mv /usr/local/lib/libgvc.so /tmp/ +``` +### Other errors +Delete `./cache/ags` and install it again. + diff --git a/src/content/docs/en/i-i/03troubleshooting.md b/src/content/docs/en/i-i/03troubleshooting.md deleted file mode 100644 index 7098c62..0000000 --- a/src/content/docs/en/i-i/03troubleshooting.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Steps for troubleshooting -layout: /src/layouts/autonum.astro ---- - -- Hit Super+T for terminal -- Restart AGS: `pkill ags; ags` -- Use some common sense. If you can't figure out, open an issue/discussion and I'll try to help. diff --git a/src/content/docs/en/i-i/04faq.md b/src/content/docs/en/i-i/04.faq.md similarity index 100% rename from src/content/docs/en/i-i/04faq.md rename to src/content/docs/en/i-i/04.faq.md diff --git a/src/content/docs/en/index.mdx b/src/content/docs/en/index.mdx index 47f6446..2fa9cd8 100644 --- a/src/content/docs/en/index.mdx +++ b/src/content/docs/en/index.mdx @@ -3,12 +3,10 @@ title: dots-hyprland wiki description: The documentation for end-4/dots-hyprland template: splash hero: - tagline: Congrats on setting up a new Starlight project! - image: - file: ../../../assets/houston.webp + tagline: Modern, accessible and flexible desktop configuration. actions: - - text: Install - link: ./i-i/01setup + - text: Quickstart + link: ./i-i/01.setup icon: right-arrow variant: primary - text: GitHub repo @@ -18,19 +16,19 @@ hero: import { Card, CardGrid } from '@astrojs/starlight/components'; -## Next steps +## Highlights - - Edit `src/content/docs/en/index.mdx` to see this page change. + + Shows open apps. Type to search/calculate/run - - Add Markdown or MDX files to `src/content/docs/en` to create new pages. + + ChatGPT and Google Gemini - - Edit your `sidebar` and other config in `astro.config.mjs`. + + Based on your wallpaper using [Material colors](https://m3.material.io/styles/color/the-color-system/key-colors-tones) - - Learn more in [the Starlight Docs](https://starlight.astro.build/). + + A lot.