diff --git a/docs/language-guide.rst b/docs/language-guide.rst
index c623b10e53..1424906c7b 100644
--- a/docs/language-guide.rst
+++ b/docs/language-guide.rst
@@ -163,7 +163,7 @@ Parameters for the function are:
 Markup generation
 -----------------
 
-Modes usually generate actual highlighting markup — ``<span>`` elements with specific class names that are defined by the ``className`` attribute:
+Modes usually generate actual highlighting markup — ``<span>`` elements with specific class names that are defined by the ``scope`` attribute:
 
 ::
 
@@ -180,7 +180,7 @@ Modes usually generate actual highlighting markup — ``<span>`` elements with s
     ]
   }
 
-Names are not required to be unique, it's quite common to have several definitions with the same name.
+Scopes are not required to be unique; it's quite common to have several definitions with the same scope.
 For example, many languages have various syntaxes for strings, comments, etc…
 
 Sometimes modes are defined only to support specific parsing rules and aren't needed in the final markup.
@@ -194,7 +194,10 @@ A classic example is an escaping sequence inside strings allowing them to contai
     contains: [{begin: '\\\\.'}],
   }
 
-For such modes, the ``className`` attribute should be omitted so they won't generate excessive markup.
+For such modes, the ``scope`` attribute should be omitted so they won't generate excessive markup.
+
+For a list of all supported scope names please see the :doc:`Scopes Reference
+</css-classes-reference>`.
 
 
 Mode attributes
diff --git a/docs/mode-reference.rst b/docs/mode-reference.rst
index cfe2e9be26..48542bd9a8 100644
--- a/docs/mode-reference.rst
+++ b/docs/mode-reference.rst
@@ -216,9 +216,9 @@ of the function as ``title``. The space(s) between would be matched, but not
 highlighted.
 
 Note: Internally, each regular expression in the array becomes a capture group
-inside a larger concatenated regex.  *These regular expressions many NOT include
-capture groups of their own yet.* If your regexes uses groups at all, they
-**must** be non-capturing, i.e. ``(?:regex)``.
+inside a larger concatenated regex.  If your regular expressions use capture 
+groups (or references) they will be auto-magically renumerated so that they 
+continue to work without any changes.
 
 For more info see issue `#3095 <https://github.com/highlightjs/highlight.js/issues/3095>`_.