diff --git a/docs/variables.md b/docs/variables.md
index 9b22c53c3621..831b3569286f 100644
--- a/docs/variables.md
+++ b/docs/variables.md
@@ -1,5 +1,33 @@
 # Workflow Variables
 
+Some fields in a workflow specification allow for variable references which are automatically substituted by Argo. 
+
+??? note "How to use variables"
+    Variables are enclosed in curly braces and **must not** include whitespace.
+
+    ``` yaml
+    apiVersion: argoproj.io/v1alpha1
+    kind: Workflow
+    metadata:
+    generateName: hello-world-parameters-
+    spec:
+    entrypoint: whalesay
+    arguments:
+        parameters:
+        - name: message
+        value: hello world
+    templates:
+    - name: whalesay
+        inputs:
+        parameters:
+        - name: message
+        container:
+        image: docker/whalesay
+        command: [cowsay]
+      # args: ["{{ inputs.parameters.message }}"]       <- bad
+        args: ["{{inputs.parameters.message}}"]         #  good
+    ```
+
 The following variables are made available to reference various metadata of a workflow:
 
 ## All Templates
diff --git a/mkdocs.yml b/mkdocs.yml
index 6d18944d737b..fde989d35b96 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,6 +14,8 @@ google_analytics:
 markdown_extensions:
   - codehilite
   - admonition
+  - pymdownx.superfences
+  - pymdownx.details
   - toc:
       permalink: true
 nav: