updates

Doxyfile

@@ -44,7 +44,7 @@ RECURSIVE              = YES
 GENERATE_TREEVIEW      = YES # required!
 DISABLE_INDEX          = NO
 FULL_SIDEBAR           = NO
-HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css doxygen-awesome-css/doxygen-awesome-sidebar-only.css
+HTML_EXTRA_STYLESHEET  = doxygen-awesome-css/doxygen-awesome.css doxygen-awesome-css/doxygen-awesome-sidebar-only.css custom.css
 HTML_COLORSTYLE        = LIGHT # required with Doxygen >= 1.9.5
 HTML_OUTPUT            = src/reference
 

custom.css

@@ -0,0 +1,28 @@
+/*https://github.com/jothepro/doxygen-awesome-css/blob/main/doxygen-awesome.css*/
+
+html {
+    --primary-color: #00cccc;
+
+    /* default spacings. Most components reference these values for spacing, to provide uniform spacing on the page. */
+    --spacing-small:  3px; /*  5px; */
+    --spacing-medium: 6px; /* 10px; */
+    --spacing-large:  10px; /* 16px; */
+
+    /*!* font sizes *!*/
+    /*--page-font-size:       14px; !* 15.6px; *!*/
+    /*--navigation-font-size: 12px; !* 14.4px; *!*/
+    /*--toc-font-size:        11px; !* 13.4px; *!*/
+    /*--code-font-size:       12px; !* 14px affects code, fragment *!*/
+    /*--title-font-size:      20px; !* 22px; *!*/
+
+    --content-line-height: 25px;
+
+    /* colors for various content boxes: @warning, @note, @deprecated @bug */
+
+    --note-color: #ddffff;
+    --note-color-dark: #00cccc;
+    --note-color-darker: #00aaaa;
+
+
+}
+

src/gettingstarted/extension/index.md

@@ -11,11 +11,11 @@ has_toc: false
 Albert can be extended by writing native C++/Qt plugins or Python plugins.
 A quick comparison:
 
-- [Native plugins](/docs/gettingstarted/extension/cplusplus):
+- [Native plugins](/gettingstarted/extension/cplusplus):
   - Performance and power of C++.
   - Access to Qt and its eventloop.
   - Dynamic config widgets.
-- [Python plugins](/docs/gettingstarted/extension/python):
+- [Python plugins](/gettingstarted/extension/python):
   - Simplicity of Python.
   - Rapid prototyping.
   - Easy to distribute/share.

src/gettingstarted/faq.md

@@ -0,0 +1,123 @@
+---
+title: FAQ
+parent: Getting started
+nav_order: 3
+---
+
+# Frequently asked questions
+{: .no_toc }
+
+- TOC
+{:toc}
+
+
+## Where are cache, config and data files stored?
+
+According to [QStandardPaths](https://doc.qt.io/qt-6/qstandardpaths.html#StandardLocation-enum) base directories are:
+
+|           | Linux/BSD                                                                                | MacOS                                                                                                                    |
+|-----------|------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|
+| Cache | 👨🏼‍💻 `~/.cache/albert`                                                                | 👨🏼‍💻 `~/Library/Caches/albert`<br>💻 `/Library/Caches/albert`                                                         |
+| Config | 👨🏼‍💻 `~/.config/albert`<br>💻 `/etc/xdg/albert`                                       | 👨🏼‍💻 `~/Library/Preferences/albert`                                                                                   |
+| Data      | 👨🏼‍💻 `~/.local/share/albert`<br>💻 `/usr/local/share/albert`<br>💻 `/usr/share/albert` | 👨🏼‍💻 `~/Library/Application Support/albert`<br>💻 `/Library/Application Support/albert`<br>💻 `<APPDIR>/../Resources` |
+
+Albert places its data in the base directories root.
+Plugins use subdirectories named by their identifier.
+In case of multiple directories the directories are considered in the given order. 
+Users may change the contents of the user 👨🏼‍💻 directories (manually or by using the app).
+Do not touch app/vendor 💻 directories!
+
+{: .note}
+Note that environment variables may change these base directories on XDG platforms.
+See [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/latest/index.html) for more information.
+
+
+## How to make hotkeys work on Wayland?
+
+Wayland hotkey adoption is still in its [infancy](https://dec05eba.com/2024/03/29/wayland-global-hotkeys-shortcut-is-mostly-useless/).
+A generic solution is to let your desktop environment handle the hotkey registration.
+Bind the hotkey to the command you want it to run, e.g. 
+
+```bash 
+albert toggle
+```
+
+- [Gnome help](https://help.gnome.org/users/gnome-help/stable/keyboard-shortcuts-set.html.en)
+- [KDE documentation](https://docs.kde.org/stable5/en/khelpcenter/fundamentals/shortcuts.html)
+- You are welcome to improve this list. 
+
+
+## How to make hotkeys have less latency?
+
+Note that the above runs a new app instance, which is relatively heavy.
+Another approach is to pipe the command you want to send directly into the albert IPC socket.
+
+```bash
+# Using netcat-openbsd
+echo -n toggle | nc -U ~/.cache/albert/ipc_socket
+
+# Using socat
+echo -n toggle | socat - ~/.cache/albert/ipc_socket
+```
+
+{: .note }
+Gnome does not invoke a shell for bindings. Use ```sh -c "<command line>"```.
+
+
+## How to open with a particular text?
+
+```bash
+albert show "trigger "
+```
+
+
+## How to avoid Wayland and use XCB platform? 
+
+```bash
+# Do not set QT_QPA_PLATFORM as it will propagate to launched apps
+albert --platform xcb
+```
+
+{: .note }
+Currently the shipped desktop entry does this for you.
+
+
+## How to get GNOME platform integration (auto dark mode)?
+
+Install [QGnomePlatform](https://github.com/FedoraQt/QGnomePlatform).
+QGnomePlatform project is unmaintained and no longer actively developed, however there is nothing else providing that good integration (afaik).
+Note that QGnomePlatform sets styles and such (read [more](https://jgrulich.cz/2023/03/08/explained-qgnomeplatform-and-adwaita-qt/#QGnomePlatform)).
+So using `QT_STYLE_OVERRIDE`/`--style` may not work as expected. Run Albert using:
+
+```bash
+# Do not set QT_QPA_PLATFORMTHEME as it will propagate to launched apps
+albert --platformtheme gnome
+```
+
+
+## How to get debug logs?
+
+```bash
+# Enable _all_ albert logs
+QT_LOGGING_RULES='albert*=true' albert
+
+# Enable all albert logs of a particular plugin
+QT_LOGGING_RULES='albert.python*=true' albert
+
+# Enable _all_ logs (albert + qt)
+QT_LOGGING_RULES='*=true' albert
+
+# Enable _all_ logs (albert + qt) with additional plugin debug info
+QT_LOGGING_RULES='*=true' QT_DEBUG_PLUGINS=1 albert
+
+# Debug DBus
+QT_LOGGING_RULES='default*=true' QDBUS_DEBUG=1 
+```
+
+
+## How to version plugins?
+
+If it has a public API `major.minor.patch` else `minor.patch`.
+Increase major if the API breaks.
+Increase minor if the API got some backward compatible additions or the user experiences noticable changes.
+In all other cases increase patch.