diff --git a/doc/source/definition.rst b/doc/source/definition.rst
index 0fcb5c470..2361a504e 100644
--- a/doc/source/definition.rst
+++ b/doc/source/definition.rst
@@ -474,6 +474,16 @@ For example, having a configuration file with that option enabled:
Will prevent JJb from failing if there are any non-initialized variables used
and replace them with the empty string instead.
+.. tip::
+
+ Defaults for variables can be set by using the ``|`` character
+ ``{var|default_value}``. This is useful if we want to allow users of the
+ job-template to not have to pass a setting if there is a common default for
+ it.
+
+ Example:
+
+ .. literalinclude:: /../../tests/yamlparser/fixtures/variable_defaults.yaml
Yaml Anchors & Aliases
^^^^^^^^^^^^^^^^^^^^^^
diff --git a/tests/yamlparser/fixtures/variable_defaults.xml b/tests/yamlparser/fixtures/variable_defaults.xml
new file mode 100644
index 000000000..74128ad5c
--- /dev/null
+++ b/tests/yamlparser/fixtures/variable_defaults.xml
@@ -0,0 +1,39 @@
+
+
+
+ <!-- Managed by Jenkins Job Builder -->
+ false
+ false
+ false
+ false
+ true
+
+
+
+
+ echo yolo
+
+
+
+
+
+
+
+
+
+ <!-- Managed by Jenkins Job Builder -->
+ false
+ false
+ false
+ false
+ true
+
+
+
+
+ echo override
+
+
+
+
+
diff --git a/tests/yamlparser/fixtures/variable_defaults.yaml b/tests/yamlparser/fixtures/variable_defaults.yaml
new file mode 100644
index 000000000..ea25c6c80
--- /dev/null
+++ b/tests/yamlparser/fixtures/variable_defaults.yaml
@@ -0,0 +1,16 @@
+- job-template:
+ name: '{name}-variable-defaults'
+
+ builders:
+ - shell: '{script|echo yolo}'
+
+- project:
+ name: default
+ jobs:
+ - '{name}-variable-defaults'
+
+- project:
+ name: override
+ jobs:
+ - '{name}-variable-defaults'
+ script: echo override