From e36aec0db9287873791008266b1b29d6cc27c094 Mon Sep 17 00:00:00 2001
From: Yubo-Cao <cao2006721@gmail.com>
Date: Fri, 19 Sep 2025 14:37:20 -0400
Subject: [PATCH 1/4] fix: Slightly improved visual consistency of the
 CitationkeyTab

---
 .../jabref/gui/actions/StandardActions.java   |   1 -
 .../keypattern/KeyPatternPropertiesView.java  |   9 -
 .../CitationKeyPatternTab.java                |   9 -
 .../jabref/gui/util/component/HelpButton.java |  24 +++
 .../main/resources/org/jabref/gui/Base.css    |   9 +
 .../keypattern/KeyPatternProperties.fxml      |   3 +-
 .../CitationKeyPatternTab.fxml                | 170 +++++++++++++-----
 7 files changed, 162 insertions(+), 63 deletions(-)

diff --git a/jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java b/jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java
index cd5dccd7f6b..60826f083e1 100644
--- a/jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java
+++ b/jabgui/src/main/java/org/jabref/gui/actions/StandardActions.java
@@ -181,7 +181,6 @@ public enum StandardActions implements Action {
 
     HELP(Localization.lang("Online help"), IconTheme.JabRefIcons.HELP, KeyBinding.HELP),
     HELP_GROUPS(Localization.lang("Open Help page"), IconTheme.JabRefIcons.HELP, KeyBinding.HELP),
-    HELP_KEY_PATTERNS(Localization.lang("Help on key patterns"), IconTheme.JabRefIcons.HELP, KeyBinding.HELP),
     HELP_REGEX_SEARCH(Localization.lang("Help on regular expression search"), IconTheme.JabRefIcons.HELP, KeyBinding.HELP),
     HELP_NAME_FORMATTER(Localization.lang("Help on Name Formatting"), IconTheme.JabRefIcons.HELP, KeyBinding.HELP),
     HELP_SPECIAL_FIELDS(Localization.lang("Help on special fields"), IconTheme.JabRefIcons.HELP, KeyBinding.HELP),
diff --git a/jabgui/src/main/java/org/jabref/gui/libraryproperties/keypattern/KeyPatternPropertiesView.java b/jabgui/src/main/java/org/jabref/gui/libraryproperties/keypattern/KeyPatternPropertiesView.java
index e391efb5370..0d1e2416d8e 100644
--- a/jabgui/src/main/java/org/jabref/gui/libraryproperties/keypattern/KeyPatternPropertiesView.java
+++ b/jabgui/src/main/java/org/jabref/gui/libraryproperties/keypattern/KeyPatternPropertiesView.java
@@ -1,16 +1,11 @@
 package org.jabref.gui.libraryproperties.keypattern;
 
 import javafx.fxml.FXML;
-import javafx.scene.control.Button;
 
-import org.jabref.gui.actions.ActionFactory;
-import org.jabref.gui.actions.StandardActions;
 import org.jabref.gui.commonfxcontrols.CitationKeyPatternsPanel;
-import org.jabref.gui.help.HelpAction;
 import org.jabref.gui.libraryproperties.AbstractPropertiesTabView;
 import org.jabref.gui.libraryproperties.PropertiesTab;
 import org.jabref.gui.preferences.GuiPreferences;
-import org.jabref.logic.help.HelpFile;
 import org.jabref.logic.l10n.Localization;
 import org.jabref.model.database.BibDatabaseContext;
 import org.jabref.model.entry.BibEntryTypesManager;
@@ -20,7 +15,6 @@
 
 public class KeyPatternPropertiesView extends AbstractPropertiesTabView<KeyPatternPropertiesViewModel> implements PropertiesTab {
 
-    @FXML private Button keyPatternHelp;
     @FXML private CitationKeyPatternsPanel bibtexKeyPatternTable;
 
     @Inject private GuiPreferences preferences;
@@ -44,9 +38,6 @@ public void initialize() {
 
         bibtexKeyPatternTable.patternListProperty().bindBidirectional(viewModel.patternListProperty());
         bibtexKeyPatternTable.defaultKeyPatternProperty().bindBidirectional(viewModel.defaultKeyPatternProperty());
-
-        ActionFactory actionFactory = new ActionFactory();
-        actionFactory.configureIconButton(StandardActions.HELP_KEY_PATTERNS, new HelpAction(HelpFile.CITATION_KEY_PATTERN, dialogService, preferences.getExternalApplicationsPreferences()), keyPatternHelp);
     }
 
     @Override
diff --git a/jabgui/src/main/java/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.java b/jabgui/src/main/java/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.java
index dac2489ca0e..288ddd4f28d 100644
--- a/jabgui/src/main/java/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.java
+++ b/jabgui/src/main/java/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.java
@@ -1,18 +1,13 @@
 package org.jabref.gui.preferences.citationkeypattern;
 
 import javafx.fxml.FXML;
-import javafx.scene.control.Button;
 import javafx.scene.control.CheckBox;
 import javafx.scene.control.RadioButton;
 import javafx.scene.control.TextField;
 
-import org.jabref.gui.actions.ActionFactory;
-import org.jabref.gui.actions.StandardActions;
 import org.jabref.gui.commonfxcontrols.CitationKeyPatternsPanel;
-import org.jabref.gui.help.HelpAction;
 import org.jabref.gui.preferences.AbstractPreferenceTabView;
 import org.jabref.gui.preferences.PreferencesTab;
-import org.jabref.logic.help.HelpFile;
 import org.jabref.logic.l10n.Localization;
 import org.jabref.model.entry.BibEntryTypesManager;
 
@@ -31,7 +26,6 @@ public class CitationKeyPatternTab extends AbstractPreferenceTabView<CitationKey
     @FXML private TextField keyPatternRegex;
     @FXML private TextField keyPatternReplacement;
     @FXML private TextField unwantedCharacters;
-    @FXML private Button keyPatternHelp;
     @FXML private CitationKeyPatternsPanel bibtexKeyPatternTable;
 
     public CitationKeyPatternTab() {
@@ -61,9 +55,6 @@ public void initialize() {
 
         bibtexKeyPatternTable.patternListProperty().bindBidirectional(viewModel.patternListProperty());
         bibtexKeyPatternTable.defaultKeyPatternProperty().bindBidirectional(viewModel.defaultKeyPatternProperty());
-
-        ActionFactory actionFactory = new ActionFactory();
-        actionFactory.configureIconButton(StandardActions.HELP_KEY_PATTERNS, new HelpAction(HelpFile.CITATION_KEY_PATTERN, dialogService, preferences.getExternalApplicationsPreferences()), keyPatternHelp);
     }
 
     @Override
diff --git a/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java b/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java
index eeb9b9c2e9c..c59ca206d55 100644
--- a/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java
+++ b/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java
@@ -1,5 +1,7 @@
 package org.jabref.gui.util.component;
 
+import javafx.beans.property.SimpleStringProperty;
+import javafx.beans.property.StringProperty;
 import javafx.scene.control.Button;
 
 import org.jabref.gui.DialogService;
@@ -14,6 +16,8 @@
 import org.jspecify.annotations.NonNull;
 
 public class HelpButton extends Button {
+    private StringProperty helpUrl;
+
     public HelpButton() {
         setGraphic(IconTheme.JabRefIcons.HELP.getGraphicNode());
         getStyleClass().add("icon-button");
@@ -38,4 +42,24 @@ public void setHelpPage(@NonNull String helpDocumentationUrl) {
     public void setHelpFile(@NonNull HelpFile helpFile, @NonNull DialogService dialogService, @NonNull ExternalApplicationsPreferences externalApplicationsPreferences) {
         setOnAction(_ -> new HelpAction(helpFile, dialogService, externalApplicationsPreferences).execute());
     }
+
+    public final StringProperty helpUrlProperty() {
+        if (helpUrl == null) {
+            helpUrl = new SimpleStringProperty(this, "helpUrl");
+            helpUrl.addListener((observable, oldValue, newValue) -> {
+                if (newValue != null && !newValue.isEmpty()) {
+                    setHelpPage(newValue);
+                }
+            });
+        }
+        return helpUrl;
+    }
+
+    public final String getHelpUrl() {
+        return helpUrlProperty().get();
+    }
+
+    public final void setHelpUrl(String url) {
+        helpUrlProperty().set(url);
+    }
 }
diff --git a/jabgui/src/main/resources/org/jabref/gui/Base.css b/jabgui/src/main/resources/org/jabref/gui/Base.css
index cdb132504ad..82d4414c6d7 100644
--- a/jabgui/src/main/resources/org/jabref/gui/Base.css
+++ b/jabgui/src/main/resources/org/jabref/gui/Base.css
@@ -1410,6 +1410,15 @@ We want to have a look that matches our icons in the tool-bar */
     -fx-background-color: -fx-control-inner-background;
 }
 
+.innerGridPane {
+    -fx-hgap: 1em;
+    -fx-vgap: 1em;
+}
+
+.prefIndent {
+    -fx-padding: 0 0 0 1.667em;
+}
+
 .code-area .text {
     -fx-fill: -fx-text-background-color;
 }
diff --git a/jabgui/src/main/resources/org/jabref/gui/libraryproperties/keypattern/KeyPatternProperties.fxml b/jabgui/src/main/resources/org/jabref/gui/libraryproperties/keypattern/KeyPatternProperties.fxml
index 6004240b2e1..c8fcc23c723 100644
--- a/jabgui/src/main/resources/org/jabref/gui/libraryproperties/keypattern/KeyPatternProperties.fxml
+++ b/jabgui/src/main/resources/org/jabref/gui/libraryproperties/keypattern/KeyPatternProperties.fxml
@@ -6,12 +6,13 @@
 <?import javafx.scene.layout.HBox?>
 <?import javafx.scene.layout.VBox?>
 <?import org.jabref.gui.commonfxcontrols.CitationKeyPatternsPanel?>
+<?import org.jabref.gui.util.component.HelpButton?>
 <fx:root spacing="10.0" type="VBox"
          xmlns="http://javafx.com/javafx" xmlns:fx="http://javafx.com/fxml"
          fx:controller="org.jabref.gui.libraryproperties.keypattern.KeyPatternPropertiesView">
     <HBox alignment="BOTTOM_LEFT" spacing="8.0">
         <Label styleClass="sectionHeader" text="%Key patterns"/>
-        <Button fx:id="keyPatternHelp" styleClass="icon-button,narrow" />
+        <HelpButton helpUrl="https://docs.jabref.org/setup/citationkeypatterns"/>
     </HBox>
     <Label text="%( Note: Press return to commit changes in the table! )"/>
     <AnchorPane VBox.vgrow="ALWAYS">
diff --git a/jabgui/src/main/resources/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.fxml b/jabgui/src/main/resources/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.fxml
index adc13ae7070..af7d1887919 100644
--- a/jabgui/src/main/resources/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.fxml
+++ b/jabgui/src/main/resources/org/jabref/gui/preferences/citationkeypattern/CitationKeyPatternTab.fxml
@@ -1,6 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
 
-<?import javafx.geometry.Insets?>
 <?import javafx.scene.control.Button?>
 <?import javafx.scene.control.CheckBox?>
 <?import javafx.scene.control.Label?>
@@ -8,60 +7,145 @@
 <?import javafx.scene.control.TextField?>
 <?import javafx.scene.control.ToggleGroup?>
 <?import javafx.scene.layout.AnchorPane?>
+<?import javafx.scene.layout.ColumnConstraints?>
+<?import javafx.scene.layout.GridPane?>
 <?import javafx.scene.layout.HBox?>
 <?import javafx.scene.layout.VBox?>
 <?import org.jabref.gui.commonfxcontrols.CitationKeyPatternsPanel?>
-<fx:root spacing="10.0" type="VBox"
-         xmlns="http://javafx.com/javafx" xmlns:fx="http://javafx.com/fxml"
-         fx:controller="org.jabref.gui.preferences.citationkeypattern.CitationKeyPatternTab">
+<?import org.jabref.gui.util.component.HelpButton?>
+<fx:root
+        spacing="10.0"
+        type="VBox"
+        xmlns="http://javafx.com/javafx"
+        xmlns:fx="http://javafx.com/fxml"
+        fx:controller="org.jabref.gui.preferences.citationkeypattern.CitationKeyPatternTab">
     <fx:define>
-        <ToggleGroup fx:id="uniqueKeyLetters"/>
+        <ToggleGroup
+                fx:id="uniqueKeyLetters"/>
     </fx:define>
-    <Label styleClass="titleHeader" text="%Citation key patterns"/>
+    <Label styleClass="titleHeader"
+           text="%Citation key patterns"/>
 
-    <Label styleClass="sectionHeader" text="%General"/>
-    <CheckBox fx:id="overwriteAllow" text="%Overwrite existing keys"/>
-    <CheckBox fx:id="overwriteWarning" text="%Warn before overwriting existing keys" disable="${!overwriteAllow.selected}">
-        <padding>
-            <Insets left="20.0"/>
-        </padding>
-    </CheckBox>
-    <CheckBox fx:id="generateOnSave" text="%Generate keys before saving (for entries without a key)"/>
-    <CheckBox fx:id="generateNewKeyOnImport" text="%Generate a new key for imported entries (overwriting their default)"/>
+    <GridPane
+            styleClass="innerGridPane">
+        <columnConstraints>
+            <ColumnConstraints
+                    hgrow="SOMETIMES"
+                    percentWidth="30.0"/>
+            <ColumnConstraints
+                    hgrow="SOMETIMES"/>
+            <ColumnConstraints
+                    hgrow="NEVER"/>
+        </columnConstraints>
 
-    <Label text="%Letters after duplicate generated keys"/>
-    <VBox spacing="10.0">
-        <RadioButton fx:id="letterStartA" text="%Start on second duplicate key with letter A (a, b, ...)" toggleGroup="$uniqueKeyLetters"/>
-        <RadioButton fx:id="letterStartB" text="%Start on second duplicate key with letter B (b, c, ...)" toggleGroup="$uniqueKeyLetters"/>
-        <RadioButton fx:id="letterAlwaysAdd" text="%Always add letter (a, b, ...) to generated keys" toggleGroup="$uniqueKeyLetters"/>
-        <padding>
-            <Insets left="20.0"/>
-        </padding>
-    </VBox>
+        <Label styleClass="sectionHeader"
+               text="%General"
+               GridPane.columnIndex="0"
+               GridPane.columnSpan="3"
+               GridPane.rowIndex="0"/>
 
-    <Label text="%Replace (regular expression)"/>
-    <HBox spacing="4.0" alignment="CENTER">
-        <TextField fx:id="keyPatternRegex" HBox.hgrow="ALWAYS"/>
-        <Label text="%by"/>
-        <TextField fx:id="keyPatternReplacement" HBox.hgrow="ALWAYS"/>
-        <padding>
-            <Insets left="20.0"/>
-        </padding>
-    </HBox>
+        <CheckBox
+                fx:id="overwriteAllow"
+                text="%Overwrite existing keys"
+                GridPane.columnIndex="0"
+                GridPane.columnSpan="3"
+                GridPane.rowIndex="1"/>
+        <HBox styleClass="prefIndent"
+              GridPane.columnIndex="0"
+              GridPane.columnSpan="3"
+              GridPane.rowIndex="2">
+            <CheckBox
+                    fx:id="overwriteWarning"
+                    text="%Warn before overwriting existing keys"
+                    disable="${!overwriteAllow.selected}"/>
+        </HBox>
+        <CheckBox
+                fx:id="generateOnSave"
+                text="%Generate keys before saving (for entries without a key)"
+                GridPane.columnIndex="0"
+                GridPane.columnSpan="3"
+                GridPane.rowIndex="3"/>
+        <CheckBox
+                fx:id="generateNewKeyOnImport"
+                text="%Generate a new key for imported entries (overwriting their default)"
+                GridPane.columnIndex="0"
+                GridPane.columnSpan="3"
+                GridPane.rowIndex="4"/>
 
-    <HBox alignment="CENTER_LEFT" spacing="10.0">
-        <Label text="%Remove the following characters:"/>
-        <TextField fx:id="unwantedCharacters" HBox.hgrow="ALWAYS"/>
-    </HBox>
+        <Label text="%Letters after duplicate generated keys"
+               GridPane.columnIndex="0"
+               GridPane.columnSpan="3"
+               GridPane.rowIndex="5"/>
+        <VBox spacing="10.0"
+              styleClass="prefIndent"
+              GridPane.columnIndex="0"
+              GridPane.columnSpan="3"
+              GridPane.rowIndex="6">
+            <RadioButton
+                    fx:id="letterStartA"
+                    text="%Start on second duplicate key with letter A (a, b, ...)"
+                    toggleGroup="$uniqueKeyLetters"/>
+            <RadioButton
+                    fx:id="letterStartB"
+                    text="%Start on second duplicate key with letter B (b, c, ...)"
+                    toggleGroup="$uniqueKeyLetters"/>
+            <RadioButton
+                    fx:id="letterAlwaysAdd"
+                    text="%Always add letter (a, b, ...) to generated keys"
+                    toggleGroup="$uniqueKeyLetters"/>
+        </VBox>
+
+        <Label text="%Replace (regular expression)"
+               GridPane.columnIndex="0"
+               GridPane.rowIndex="7"/>
+        <HBox spacing="4.0"
+              alignment="CENTER_LEFT"
+              GridPane.columnIndex="1"
+              GridPane.rowIndex="7">
+            <TextField
+                    fx:id="keyPatternRegex"
+                    HBox.hgrow="ALWAYS"/>
+            <Label text="%by"/>
+            <TextField
+                    fx:id="keyPatternReplacement"
+                    HBox.hgrow="ALWAYS"/>
+        </HBox>
+        <HelpButton
+                helpUrl="https://docs.jabref.org/setup/citationkeypatterns#replace-via-regular-expression"
+                GridPane.columnIndex="2"
+                GridPane.rowIndex="7"/>
 
-    <HBox>
-        <Label styleClass="sectionHeader" text="%Key patterns"/>
-        <HBox HBox.hgrow="ALWAYS"/>
-        <Button fx:id="keyPatternHelp" prefWidth="20.0"/>
+        <Label text="%Remove the following characters:"
+               GridPane.columnIndex="0"
+               GridPane.rowIndex="8"/>
+        <TextField
+                fx:id="unwantedCharacters"
+                GridPane.columnIndex="1"
+                GridPane.rowIndex="8"/>
+    </GridPane>
+
+
+    <HBox spacing="8.0">
+        <Label styleClass="sectionHeader"
+               text="%Key patterns"/>
+        <VBox alignment="BOTTOM_CENTER" >
+            <HelpButton
+                    helpUrl="https://docs.jabref.org/setup/citationkeypatterns"
+                    styleClass="headerHelpButton"
+            />
+        </VBox>
     </HBox>
+
     <Label text="%( Note: Press return to commit changes in the table! )"/>
     <AnchorPane>
-        <CitationKeyPatternsPanel fx:id="bibtexKeyPatternTable" AnchorPane.leftAnchor="0.0" AnchorPane.rightAnchor="0.0" prefHeight="180.0"/>
-        <Button text="%Reset All" onAction="#resetAllKeyPatterns" AnchorPane.rightAnchor="0.0" AnchorPane.topAnchor="0.0"/>
+        <CitationKeyPatternsPanel
+                fx:id="bibtexKeyPatternTable"
+                AnchorPane.leftAnchor="0.0"
+                AnchorPane.rightAnchor="0.0"
+                prefHeight="180.0"/>
+        <Button text="%Reset All"
+                onAction="#resetAllKeyPatterns"
+                AnchorPane.rightAnchor="0.0"
+                AnchorPane.topAnchor="0.0"/>
     </AnchorPane>
 </fx:root>

From f955c7b5efda14e4d7ea3a92ceff8ba4e25cf5a5 Mon Sep 17 00:00:00 2001
From: Yubo-Cao <cao2006721@gmail.com>
Date: Fri, 19 Sep 2025 14:41:12 -0400
Subject: [PATCH 2/4] docs: Update CHANGELOG

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc6dc313514..dc256384181 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,6 +95,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv
 - We improved the event viewer for debugging [#13783](https://github.com/JabRef/jabref/pull/13783).
 - We improved "REDACTED" replacement of API key value in web fetcher search URL [#13796](https://github.com/JabRef/jabref/issues/13796)
 - When the pin "Keep dialog always on top" in the global search dialog is selected, the search window stays open when double-clicking on an entry. [#13840](https://github.com/JabRef/jabref/issues/13840)
+- We improved the UI of regex replacement in the citation key generator tab.
 
 ### Fixed
 

From 518233417f811e9b8d2553fdde5688ea5a0f21eb Mon Sep 17 00:00:00 2001
From: Yubo Cao <Cao2006721@gmail.com>
Date: Fri, 19 Sep 2025 16:34:09 -0400
Subject: [PATCH 3/4] docs: Update CHANGELOG.md

Co-authored-by: Subhramit Basu <subhramit.bb@live.in>
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index dc256384181..1bd08c77625 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -95,7 +95,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv
 - We improved the event viewer for debugging [#13783](https://github.com/JabRef/jabref/pull/13783).
 - We improved "REDACTED" replacement of API key value in web fetcher search URL [#13796](https://github.com/JabRef/jabref/issues/13796)
 - When the pin "Keep dialog always on top" in the global search dialog is selected, the search window stays open when double-clicking on an entry. [#13840](https://github.com/JabRef/jabref/issues/13840)
-- We improved the UI of regex replacement in the citation key generator tab.
+- We improved the UI of regex replacement in the citation key generator tab. [#13939](https://github.com/JabRef/jabref/pull/13939)
 
 ### Fixed
 

From 54b7c18eb5845866eb9b9e2159268c588180b20c Mon Sep 17 00:00:00 2001
From: Yubo-Cao <cao2006721@gmail.com>
Date: Fri, 19 Sep 2025 18:19:36 -0400
Subject: [PATCH 4/4] fix: Make the HelpButton's weird method more clear

---
 .../jabref/gui/util/component/HelpButton.java | 53 ++++++++++---------
 .../EntryTableConfigurationDialog.java        |  2 +-
 .../LargeLibraryOptimizationDialog.java       |  2 +-
 .../MainFileDirectoryDialog.java              |  2 +-
 .../quicksettings/OnlineServicesDialog.java   |  6 +--
 .../quicksettings/PushApplicationDialog.java  |  2 +-
 .../welcome/quicksettings/ThemeDialog.java    |  2 +-
 7 files changed, 37 insertions(+), 32 deletions(-)

diff --git a/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java b/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java
index c59ca206d55..9cae2f5a188 100644
--- a/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java
+++ b/jabgui/src/main/java/org/jabref/gui/util/component/HelpButton.java
@@ -10,56 +10,61 @@
 import org.jabref.gui.help.HelpAction;
 import org.jabref.gui.icon.IconTheme;
 import org.jabref.gui.preferences.GuiPreferences;
+import org.jabref.gui.util.BindingsHelper;
 import org.jabref.logic.help.HelpFile;
 
 import com.airhacks.afterburner.injection.Injector;
 import org.jspecify.annotations.NonNull;
 
 public class HelpButton extends Button {
-    private StringProperty helpUrl;
+    private final StringProperty helpUrl = new SimpleStringProperty("");
+    private boolean isHelpFileSet = false;
 
     public HelpButton() {
         setGraphic(IconTheme.JabRefIcons.HELP.getGraphicNode());
         getStyleClass().add("icon-button");
         setPrefSize(28, 28);
         setMinSize(28, 28);
+        BindingsHelper.subscribeFuture(helpUrl, (url) -> {
+            if (url == null || url.isBlank()) {
+                throw new IllegalArgumentException("Help URL must be non-null and non-blank");
+            }
+            if (isHelpFileSet) {
+                throw new IllegalStateException("Help file has already been set");
+            }
+            setOnAction(_ -> new OpenBrowserAction(helpUrl.get(), Injector.instantiateModelOrService(DialogService.class), Injector.instantiateModelOrService(GuiPreferences.class).getExternalApplicationsPreferences()).execute());
+        });
     }
 
     public HelpButton(@NonNull String url) {
         this();
-        setHelpPage(url);
-    }
-
-    public void setHelpPage(@NonNull String helpDocumentationUrl) {
-        setOnAction(
-                _ -> new OpenBrowserAction(helpDocumentationUrl,
-                        Injector.instantiateModelOrService(DialogService.class),
-                        Injector.instantiateModelOrService(GuiPreferences.class).getExternalApplicationsPreferences()
-                ).execute()
-        );
+        setHelpUrl(url);
     }
 
     public void setHelpFile(@NonNull HelpFile helpFile, @NonNull DialogService dialogService, @NonNull ExternalApplicationsPreferences externalApplicationsPreferences) {
+        if (isHelpFileSet) {
+            throw new IllegalStateException("Help file has already been set");
+        }
+        isHelpFileSet = true;
+        if (!helpUrl.get().isBlank()) {
+            throw new IllegalArgumentException("You cannot set both a help URL and a help file");
+        }
         setOnAction(_ -> new HelpAction(helpFile, dialogService, externalApplicationsPreferences).execute());
     }
 
-    public final StringProperty helpUrlProperty() {
-        if (helpUrl == null) {
-            helpUrl = new SimpleStringProperty(this, "helpUrl");
-            helpUrl.addListener((observable, oldValue, newValue) -> {
-                if (newValue != null && !newValue.isEmpty()) {
-                    setHelpPage(newValue);
-                }
-            });
-        }
+    /// This method is not used by JabRef, but provided for FXML usage.
+    public StringProperty helpUrlProperty() {
         return helpUrl;
     }
 
-    public final String getHelpUrl() {
-        return helpUrlProperty().get();
+    /// This method is not used by JabRef, but provided for FXML usage.
+    public String getHelpUrl() {
+        return helpUrl.get();
     }
 
-    public final void setHelpUrl(String url) {
-        helpUrlProperty().set(url);
+    /// This method is used both internally in JabRef's code base, but also
+    /// for FXML usage. Do not refactor this.
+    public void setHelpUrl(@NonNull String helpUrl) {
+        this.helpUrl.setValue(helpUrl);
     }
 }
diff --git a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/EntryTableConfigurationDialog.java b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/EntryTableConfigurationDialog.java
index f14bb8a40a6..911f2616ecd 100644
--- a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/EntryTableConfigurationDialog.java
+++ b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/EntryTableConfigurationDialog.java
@@ -45,6 +45,6 @@ private void initialize() {
 
         showCitationKeyBox.selectedProperty().bindBidirectional(viewModel.showCitationKeyProperty());
 
-        helpButton.setHelpPage(URLs.ENTRY_TABLE_COLUMNS_DOC);
+        helpButton.setHelpUrl(URLs.ENTRY_TABLE_COLUMNS_DOC);
     }
 }
diff --git a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/LargeLibraryOptimizationDialog.java b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/LargeLibraryOptimizationDialog.java
index 9ffb88706f0..edfd32e23a2 100644
--- a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/LargeLibraryOptimizationDialog.java
+++ b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/LargeLibraryOptimizationDialog.java
@@ -53,6 +53,6 @@ private void initialize() {
         disableAutosave.selectedProperty().bindBidirectional(viewModel.disableAutosaveProperty());
         disableGroupCount.selectedProperty().bindBidirectional(viewModel.disableGroupCountProperty());
 
-        helpButton.setHelpPage(URLs.PERFORMANCE_DOC);
+        helpButton.setHelpUrl(URLs.PERFORMANCE_DOC);
     }
 }
diff --git a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/MainFileDirectoryDialog.java b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/MainFileDirectoryDialog.java
index cb10f3a6fbd..9d9fc9e9a9c 100644
--- a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/MainFileDirectoryDialog.java
+++ b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/MainFileDirectoryDialog.java
@@ -48,7 +48,7 @@ private void initialize() {
         viewModel = new MainFileDirectoryDialogViewModel(preferences, dialogService);
 
         pathField.textProperty().bindBidirectional(viewModel.pathProperty());
-        helpButton.setHelpPage(URLs.FILE_LINKS_DOC);
+        helpButton.setHelpUrl(URLs.FILE_LINKS_DOC);
     }
 
     @FXML
diff --git a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/OnlineServicesDialog.java b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/OnlineServicesDialog.java
index da0cc2e0417..9bec9508ee7 100644
--- a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/OnlineServicesDialog.java
+++ b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/OnlineServicesDialog.java
@@ -66,9 +66,9 @@ private void initialize() {
 
         populateFetchers();
 
-        helpButton.setHelpPage(URLs.ONLINE_SERVICES_DOC);
-        grobidHelpButton.setHelpPage(URLs.GROBID_DOC);
-        fetchersHelpButton.setHelpPage(URLs.ONLINE_SERVICES_DOC);
+        helpButton.setHelpUrl(URLs.ONLINE_SERVICES_DOC);
+        grobidHelpButton.setHelpUrl(URLs.GROBID_DOC);
+        fetchersHelpButton.setHelpUrl(URLs.ONLINE_SERVICES_DOC);
     }
 
     private void populateFetchers() {
diff --git a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/PushApplicationDialog.java b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/PushApplicationDialog.java
index 3766aabe74f..5285f294050 100644
--- a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/PushApplicationDialog.java
+++ b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/PushApplicationDialog.java
@@ -63,7 +63,7 @@ private void initialize() {
 
         pathField.textProperty().bindBidirectional(viewModel.pathProperty());
         pathField.textProperty().addListener((_, _, newText) -> updatePathValidation(newText));
-        helpButton.setHelpPage(URLs.PUSH_TO_APPLICATIONS_DOC);
+        helpButton.setHelpUrl(URLs.PUSH_TO_APPLICATIONS_DOC);
     }
 
     private void updatePathValidation(String newText) {
diff --git a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/ThemeDialog.java b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/ThemeDialog.java
index 8f9fe431909..850892e0290 100644
--- a/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/ThemeDialog.java
+++ b/jabgui/src/main/java/org/jabref/gui/welcome/quicksettings/ThemeDialog.java
@@ -81,7 +81,7 @@ private void initialize() {
         selectInitialTheme();
         updateCustomThemeVisibility(viewModel.getSelectedTheme() == ThemeTypes.CUSTOM);
 
-        helpButton.setHelpPage(URLs.CUSTOM_THEME_DOC);
+        helpButton.setHelpUrl(URLs.CUSTOM_THEME_DOC);
     }
 
     private void selectInitialTheme() {