Ensure all GitLab reference chars are checked

and add some documentation

doc/user/markdown.md

@@ -462,7 +462,8 @@ GitLab Flavored Markdown recognizes the following:
 
 For example, referencing an issue by using `#123` formats the output as a link
 to issue number 123 with text `#123`. Likewise, a link to issue number 123 is
-recognized and formatted with text `#123`.
+recognized and formatted with text `#123`.  If you don't want `#123` to link to an issue,
+add a leading backslash `\#123`.
 
 In addition to this, links to some objects are also recognized and formatted. Some examples of these are:
 

lib/banzai/filter/markdown_pre_escape_filter.rb

@@ -25,7 +25,8 @@ module Banzai
     # does the conversion into span tags.
     class MarkdownPreEscapeFilter < HTML::Pipeline::TextFilter
       # We just need to target those that are special GitLab references
-      ASCII_PUNCTUATION = %r{([\\][@#!$&~%^])}.freeze
+      REFERENCE_CHARACTERS = '@#!$&~%^'
+      ASCII_PUNCTUATION    = %r{([\\][#{REFERENCE_CHARACTERS}])}.freeze
       LITERAL_KEYWORD      = 'cmliteral'
 
       def call

spec/lib/banzai/pipeline/plain_markdown_pipeline_spec.rb

@@ -33,8 +33,11 @@ RSpec.describe Banzai::Pipeline::PlainMarkdownPipeline do
 
     describe 'CommonMark tests', :aggregate_failures do
       it 'converts all reference punctuation to literals' do
-        markdown = %q(\@\#\!\$\&\~\%\^)
-        punctuation = %w(@ # ! $ ~ % ^)
+        reference_chars = Banzai::Filter::MarkdownPreEscapeFilter::REFERENCE_CHARACTERS
+        markdown = reference_chars.split('').map {|char| char.prepend("\\") }.join
+        punctuation = Banzai::Filter::MarkdownPreEscapeFilter::REFERENCE_CHARACTERS.split('')
+        punctuation = punctuation.delete_if {|char| char == '&' }
+        punctuation << '&amp;'
 
         result = described_class.call(markdown, project: project)
         output = result[:output].to_html
@@ -43,6 +46,20 @@ RSpec.describe Banzai::Pipeline::PlainMarkdownPipeline do
         expect(result[:escaped_literals]).to be_truthy
       end
 
+      it 'ensure we handle all the GitLab reference characters' do
+        reference_chars = ObjectSpace.each_object(Class).map do |klass|
+          next unless klass.included_modules.include?(Referable)
+          next unless klass.respond_to?(:reference_prefix)
+          next unless klass.reference_prefix.length == 1
+
+          klass.reference_prefix
+        end.compact
+
+        reference_chars.all? do |char|
+          Banzai::Filter::MarkdownPreEscapeFilter::REFERENCE_CHARACTERS.include?(char)
+        end
+      end
+
       it 'does not convert non-reference punctuation to spans' do
         markdown = %q(\"\'\*\+\,\-\.\/\:\;\<\=\>\?\[\]\_\`\{\|\}) + %q[\(\)\\\\]