diff --git a/src/main.cc b/src/main.cc
index 1b97425e..db8a24f6 100644
--- a/src/main.cc
+++ b/src/main.cc
@@ -311,10 +311,13 @@ int main( int argc, char ** argv )
   // GoldenDict use lots of X11 functions and it currently cannot work
   // natively on Wayland. This workaround will force GoldenDict to use
   // XWayland.
-  char * xdg_envc     = getenv( "XDG_SESSION_TYPE" );
-  QString xdg_session = xdg_envc ? QString::fromLatin1( xdg_envc ) : QString();
-  if ( !QString::compare( xdg_session, QString( "wayland" ), Qt::CaseInsensitive ) ) {
-    setenv( "QT_QPA_PLATFORM", "xcb", 1 );
+
+  if ( qEnvironmentVariableIsEmpty( "GOLDENDICT_FORCE_WAYLAND" ) ) {
+    char * xdg_envc     = getenv( "XDG_SESSION_TYPE" );
+    QString xdg_session = xdg_envc ? QString::fromLatin1( xdg_envc ) : QString();
+    if ( !QString::compare( xdg_session, QString( "wayland" ), Qt::CaseInsensitive ) ) {
+      setenv( "QT_QPA_PLATFORM", "xcb", 1 );
+    }
   }
 #endif
 
diff --git a/src/ui/mainwindow.cc b/src/ui/mainwindow.cc
index a9d69aa6..771df2bb 100644
--- a/src/ui/mainwindow.cc
+++ b/src/ui/mainwindow.cc
@@ -2856,6 +2856,12 @@ void MainWindow::toggleMainWindow( bool onlyShow )
 
 void MainWindow::installHotKeys()
 {
+#if defined( Q_OS_LINUX )
+  if ( !qEnvironmentVariableIsEmpty( "GOLDENDICT_FORCE_WAYLAND" ) ) {
+    return;
+  }
+#endif
+
   hotkeyWrapper.reset(); // Remove the old one
 
   if ( cfg.preferences.enableMainWindowHotkey || cfg.preferences.enableClipboardHotkey ) {
diff --git a/website/docs/topic_wayland.md b/website/docs/topic_wayland.md
new file mode 100644
index 00000000..dd8808db
--- /dev/null
+++ b/website/docs/topic_wayland.md
@@ -0,0 +1,16 @@
+Environment variable `GOLDENDICT_FORCE_WAYLAND` can be used to force GD to run in Wayland mode, like `env GOLDENDICT_FORCE_WAYLAND=1 goldendict`.
+
+!!! danger "Don't use unless you know!"
+    This flag only guarantees GD to run in wayland mode and won't crash, but nothing more.
+
+    Enable this will break scan popup, global hotkeys and probably other things.
+
+## Current reality
+
+!!! note "Help wanted"
+    Need help to redesign scan popup for wayland.
+
+Scan popup is implemented with `querying mouse cursor's position` and `setting a window's absolute global position`.
+Wayland does not support both by design and philosophy.
+
+Wayland does not support registering global hotkeys until very recently, but a reasonable wayland desktop environment should provide some way to bind keys to commands globally.
\ No newline at end of file
diff --git a/website/mkdocs.yml b/website/mkdocs.yml
index 4dde31fa..5a592294 100644
--- a/website/mkdocs.yml
+++ b/website/mkdocs.yml
@@ -44,6 +44,7 @@ nav:
       - Custom transliteration: topic_transliteration.md
       - Customize Dictionary: custom_dictionary.md
       - OCR Integration: howto/ocr.md
+      - Wayland/Linux: topic_wayland.md
   - Report Bugs & Feedbacks: feedbacks.md
   - Contributor Guides:
     - Developer: developer.md