jazzy 0.13.7 → 0.14.2

data/lib/jazzy/doc_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'fileutils'
 require 'mustache'
 require 'pathname'
@@ -51,8 +53,8 @@ module Jazzy
 
     def self.children_for_doc(doc)
       doc.children
-         .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
-         .flat_map do |child|
+        .sort_by { |c| [c.nav_order, c.name, c.usr || ''] }
+        .flat_map do |child|
         # FIXME: include arbitrarily nested extensible types
         [{ name: child.name, url: child.url }] +
           Array(child.children.select do |sub_child|
@@ -68,8 +70,7 @@ module Jazzy
     # @return [SourceModule] the documented source module
     def self.build(options)
       if options.sourcekitten_sourcefile_configured
-        stdout = '[' + options.sourcekitten_sourcefile.map(&:read)
-                              .join(',') + ']'
+        stdout = "[#{options.sourcekitten_sourcefile.map(&:read).join(',')}]"
       elsif options.podspec_configured
         pod_documenter = PodspecDocumenter.new(options.podspec)
         stdout = pod_documenter.sourcekitten_output(options)
@@ -104,6 +105,7 @@ module Jazzy
     def self.each_doc(output_dir, docs, &block)
       docs.each do |doc|
         next unless doc.render_as_page?
+
         # Filepath is relative to documentation root:
         path = output_dir + doc.filepath
         block.call(doc, path)
@@ -132,8 +134,8 @@ module Jazzy
         SearchBuilder.build(source_module, output_dir)
       end
 
-      copy_assets(output_dir)
-      copy_extensions(output_dir)
+      copy_extensions(source_module, output_dir)
+      copy_theme_assets(output_dir)
 
       DocsetBuilder.new(output_dir, source_module).build!
 
@@ -170,7 +172,7 @@ module Jazzy
 
     def self.relative_path_if_inside(path, base_path)
       relative = path.relative_path_from(base_path)
-      if relative.to_path =~ %r{/^..(\/|$)/}
+      if relative.to_path =~ %r{/^..(/|$)/}
         path
       else
         relative
@@ -181,7 +183,7 @@ module Jazzy
       decls.map do |decl|
         {
           file: decl.file,
-          line: decl.line || decl.start_line,
+          line: decl.start_line || decl.line,
           symbol: decl.fully_qualified_name,
           symbol_kind: decl.type.kind,
           warning: 'undocumented',
@@ -206,7 +208,7 @@ module Jazzy
       end
     end
 
-    def self.copy_assets(destination)
+    def self.copy_theme_assets(destination)
       assets_directory = Config.instance.theme_directory + 'assets'
       FileUtils.cp_r(assets_directory.children, destination)
       Pathname.glob(destination + 'css/**/*.scss').each do |scss|
@@ -217,12 +219,15 @@ module Jazzy
       end
     end
 
-    def self.copy_extensions(destination)
+    def self.copy_extensions(source_module, destination)
+      if source_host = source_module.host&.extension
+        copy_extension(source_host, destination)
+      end
       copy_extension('katex', destination) if Markdown.has_math
     end
 
     def self.copy_extension(name, destination)
-      ext_directory = Pathname(__FILE__).parent + 'extensions/' + name
+      ext_directory = Pathname(__dir__) / 'extensions' / name
       FileUtils.cp_r(ext_directory.children, destination)
     end
 
@@ -231,26 +236,42 @@ module Jazzy
       SourceKitten.autolink_document(html, doc_model)
     end
 
+    def self.render_inline(doc_model, markdown)
+      html = Markdown.render_inline(markdown)
+      SourceKitten.autolink_document(html, doc_model)
+    end
+
+    # Build Mustache document - common fields between page types
+    def self.new_document(source_module, doc_model)
+      Doc.new.tap do |doc|
+        doc[:custom_head] = Config.instance.custom_head
+        doc[:disable_search] = Config.instance.disable_search
+        doc[:doc_coverage] = source_module.doc_coverage unless
+          Config.instance.hide_documentation_coverage
+        doc[:structure] = source_module.doc_structure
+        doc[:module_name] = source_module.name
+        doc[:author_name] = source_module.author_name
+        if source_host = source_module.host
+          doc[:source_host_name] = source_host.name
+          doc[:source_host_url] = source_host.url
+          doc[:source_host_image] = source_host.image
+          doc[:source_host_item_url] = source_host.item_url(doc_model)
+          doc[:github_url] = doc[:source_host_url]
+          doc[:github_token_url] = doc[:source_host_item_url]
+        end
+        doc[:dash_url] = source_module.dash_url
+      end
+    end
+
     # Build Mustache document from a markdown source file
-    # @param [Config] options Build options
+    # @param [SourceModule] module-wide settings
     # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     # @param [String] path_to_root
-    # @param [Array] doc_structure doc structure comprised of section names and
-    #        child names and URLs. @see doc_structure_for_docs
     def self.document_markdown(source_module, doc_model, path_to_root)
-      doc = Doc.new # Mustache model instance
+      doc = new_document(source_module, doc_model)
       name = doc_model.name == 'index' ? source_module.name : doc_model.name
       doc[:name] = name
       doc[:overview] = render(doc_model, doc_model.content(source_module))
-      doc[:custom_head] = Config.instance.custom_head
-      doc[:disable_search] = Config.instance.disable_search
-      doc[:doc_coverage] = source_module.doc_coverage unless
-        Config.instance.hide_documentation_coverage
-      doc[:structure] = source_module.doc_structure
-      doc[:module_name] = source_module.name
-      doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url
-      doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:hide_name] = true
       doc.render.gsub(ELIDED_AUTOLINK_TOKEN, path_to_root)
@@ -324,30 +345,6 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    def self.should_link_to_github(file)
-      return unless file
-      file = file.realpath.to_path
-      source_directory = Config.instance.source_directory.to_path
-      file.start_with?(source_directory)
-    end
-
-    # Construct Github token URL
-    # @param [Hash] item Parsed doc child item
-    # @param [Config] options Build options
-    def self.gh_token_url(item, source_module)
-      return unless github_prefix = source_module.github_file_prefix
-      return unless should_link_to_github(item.file)
-      gh_line = if item.start_line && (item.start_line != item.end_line)
-                  "#L#{item.start_line}-L#{item.end_line}"
-                else
-                  "#L#{item.line}"
-                end
-      relative_file_path = item.file.realpath.relative_path_from(
-        source_module.root_path,
-      )
-      "#{github_prefix}/#{relative_file_path}#{gh_line}"
-    end
-
     # Build mustache item for a top-level doc
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
@@ -355,27 +352,31 @@ module Jazzy
     def self.render_item(item, source_module)
       # Combine abstract and discussion into abstract
       abstract = (item.abstract || '') + (item.discussion || '')
+      source_host_item_url = source_module.host&.item_url(item)
       {
-        name:                       item.name,
-        name_html:                  item.name.gsub(':', ':<wbr>'),
-        abstract:                   abstract,
-        declaration:                item.display_declaration,
-        language:                   item.display_language,
+        name: item.name,
+        name_html: item.name.gsub(':', ':<wbr>'),
+        abstract: abstract,
+        declaration: item.display_declaration,
+        language: item.display_language,
         other_language_declaration: item.display_other_language_declaration,
-        usr:                        item.usr,
-        dash_type:                  item.type.dash_type,
-        github_token_url:           gh_token_url(item, source_module),
-        default_impl_abstract:      item.default_impl_abstract,
-        from_protocol_extension:    item.from_protocol_extension,
-        return:                     item.return,
-        parameters:                 (item.parameters if item.parameters.any?),
-        url:                        (item.url if item.render_as_page?),
-        start_line:                 item.start_line,
-        end_line:                   item.end_line,
-        direct_link:                item.omit_content_from_parent?,
-        deprecation_message:        item.deprecation_message,
-        unavailable_message:        item.unavailable_message,
-        usage_discouraged:          item.usage_discouraged?,
+        usr: item.usr,
+        dash_type: item.type.dash_type,
+        source_host_item_url: source_host_item_url,
+        github_token_url: source_host_item_url,
+        default_impl_abstract: item.default_impl_abstract,
+        from_protocol_extension: item.from_protocol_extension,
+        return: item.return,
+        parameters: (item.parameters if item.parameters.any?),
+        url: (item.url if item.render_as_page?),
+        start_line: item.start_line,
+        end_line: item.end_line,
+        direct_link: item.omit_content_from_parent?,
+        deprecation_message: item.deprecation_message,
+        unavailable_message: item.unavailable_message,
+        usage_discouraged: item.usage_discouraged?,
+        async: item.async,
+        declaration_note: item.declaration_note,
       }
     end
     # rubocop:enable Metrics/MethodLength
@@ -383,7 +384,7 @@ module Jazzy
     def self.make_task(mark, uid, items, doc_model)
       {
         name: mark.name,
-        name_html: (render(doc_model, mark.name) if mark.name),
+        name_html: (render_inline(doc_model, mark.name) if mark.name),
         uid: ERB::Util.url_encode(uid),
         items: items,
         pre_separator: mark.has_start_dash,
@@ -412,12 +413,10 @@ module Jazzy
     end
 
     # rubocop:disable Metrics/MethodLength
-    # Build Mustache document from single parsed doc
-    # @param [Config] options Build options
+    # Build Mustache document from single parsed decl
+    # @param [SourceModule] module-wide settings
     # @param [Hash] doc_model Parsed doc. @see SourceKitten.parse
     # @param [String] path_to_root
-    # @param [Array] doc_structure doc structure comprised of section names and
-    #        child names and URLs. @see doc_structure_for_docs
     def self.document(source_module, doc_model, path_to_root)
       if doc_model.type.markdown?
         return document_markdown(source_module, doc_model, path_to_root)
@@ -429,11 +428,7 @@ module Jazzy
         overview = render(doc_model, alternative_abstract) + overview
       end
 
-      doc = Doc.new # Mustache model instance
-      doc[:custom_head] = Config.instance.custom_head
-      doc[:disable_search] = Config.instance.disable_search
-      doc[:doc_coverage] = source_module.doc_coverage unless
-        Config.instance.hide_documentation_coverage
+      doc = new_document(source_module, doc_model)
       doc[:name] = doc_model.name
       doc[:kind] = doc_model.type.name
       doc[:dash_type] = doc_model.type.dash_type
@@ -444,13 +439,7 @@ module Jazzy
       doc[:overview] = overview
       doc[:parameters] = doc_model.parameters
       doc[:return] = doc_model.return
-      doc[:structure] = source_module.doc_structure
       doc[:tasks] = render_tasks(source_module, doc_model.children)
-      doc[:module_name] = source_module.name
-      doc[:author_name] = source_module.author_name
-      doc[:github_url] = source_module.github_url
-      doc[:github_token_url] = gh_token_url(doc_model, source_module)
-      doc[:dash_url] = source_module.dash_url
       doc[:path_to_root] = path_to_root
       doc[:deprecation_message] = doc_model.deprecation_message
       doc[:unavailable_message] = doc_model.unavailable_message

data/lib/jazzy/docset_builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mustache'
 require 'sqlite3'
 
@@ -89,7 +91,7 @@ module Jazzy
         (output_dir + "#{source_module.name}.xml").open('w') do |xml|
           url = URI.join(config.root_url, "docsets/#{source_module.name}.tgz")
           xml << "<entry><version>#{config.version}</version><url>#{url}" \
-                 "</url></entry>\n"
+            "</url></entry>\n"
         end
       end
     end

data/lib/jazzy/documentation_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'pathname'
 
 require 'jazzy/jazzy_markdown'
@@ -12,19 +14,21 @@ module Jazzy
         SourceDocument.new.tap do |sd|
           sd.name = File.basename(file_path, '.md')
           sd.overview = overview Pathname(file_path)
-          sd.usr = 'documentation.' + sd.name
+          sd.usr = "documentation.#{sd.name}"
         end
       end
     end
 
     def self.overview(file_path)
-      return '' unless file_path && file_path.exist?
+      return '' unless file_path&.exist?
+
       file_path.read
     end
 
     def self.documentation_entries
       return [] unless
         config.documentation_glob_configured && config.documentation_glob
+
       config.documentation_glob.select { |e| File.file? e }
     end
   end

data/lib/jazzy/executable.rb

@@ -1,7 +1,10 @@
+# frozen_string_literal: true
+
 module Jazzy
   module Executable
     class IO < Array
       def initialize(io = nil)
+        super()
         @io = io
       end
 

data/lib/jazzy/extensions/bitbucket/img/bitbucket.svg

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg fill="none" version="1.1" viewBox="0 0 24 21.58" xmlns="http://www.w3.org/2000/svg">
+ <path d="m22.95 7.2332h-7.1932l-1.1989 7.0734h-4.9953l-5.8745 6.9934s0.27972 0.2398 0.67935 0.2398h15.665c0.3597 0 0.6794-0.2797 0.7593-0.6394z" fill="url(#paint0_linear)"/>
+ <path d="m0.77041 0c-0.47956 0-0.83918 0.43959-0.75926 0.87918l3.237 19.822c0.03996 0.2398 0.15986 0.4796 0.35968 0.6394 0 0 0.27972 0.2398 0.67935 0.2398l6.0743-7.2732h-0.8392l-1.3188-7.0734h14.746l1.039-6.3541c0.08-0.47955-0.2797-0.87918-0.7593-0.87918z" fill="#fff"/>
+ <defs>
+  <linearGradient id="paint0_linear" x1="27.898" x2="16.618" y1="15.387" y2="23.023" gradientTransform="translate(-4 -5)" gradientUnits="userSpaceOnUse">
+   <stop stop-color="#fff" stop-opacity=".4" offset=".071833"/>
+   <stop stop-color="#fff" offset="1"/>
+  </linearGradient>
+ </defs>
+</svg>

data/lib/jazzy/extensions/gitlab/img/gitlab.svg

@@ -0,0 +1,23 @@
+<svg
+   xmlns="http://www.w3.org/2000/svg"
+   height="313.44601"
+   width="338.96616"
+   xml:space="preserve"
+   viewBox="0 0 338.96616 313.44601"
+   y="0px"
+   x="0px"
+   version="1.1">
+<style
+   id="style10"
+   type="text/css">
+	.st2{fill:#FFFFFF;}
+</style>
+<g
+   transform="translate(-123.54995,-122.776)"
+   id="logo_art">
+	<path
+   id="path12"
+   d="m 461.514,298.355 -18.049,-55.587 c 0.008,0.025 0.011,0.051 0.019,0.076 -0.009,-0.029 -0.014,-0.058 -0.022,-0.087 -10e-4,-0.002 -10e-4,-0.003 -10e-4,-0.005 0,-0.001 0,-0.002 0,-0.002 l -35.83,-110.31 c -1.96,-5.811 -7.353,-9.711 -13.536,-9.663 -6.201,0.032 -11.446,3.857 -13.364,9.748 L 346.721,237.23 H 239.408 L 205.334,132.518 c -1.916,-5.886 -7.162,-9.71 -13.362,-9.742 -0.025,0 -0.049,0 -0.075,0 -6.105,0 -11.509,3.876 -13.49,9.752 l -35.732,110.211 -0.005,0.014 c 0,0.001 0,0.002 0,0.003 -0.009,0.028 -0.013,0.056 -0.022,0.084 0.008,-0.025 0.011,-0.051 0.019,-0.076 l -18.115,55.591 c -2.725,8.392 0.232,17.512 7.36,22.697 L 288.328,434.7 c 0.023,0.017 0.049,0.027 0.072,0.044 0.067,0.048 0.132,0.097 0.2,0.142 -0.064,-0.043 -0.124,-0.09 -0.187,-0.134 0,0 0,-0.001 -0.001,-0.001 0.01,0.008 0.022,0.013 0.033,0.02 0.009,0.006 0.018,0.01 0.027,0.016 0.001,0.001 0.002,0.002 0.004,0.003 0.242,0.168 0.493,0.322 0.753,0.463 0.036,0.02 0.068,0.045 0.104,0.064 10e-4,0 10e-4,10e-4 0.002,10e-4 0.022,0.011 0.042,0.025 0.064,0.036 0.017,0.008 0.035,0.013 0.051,0.021 0.012,0.006 0.025,0.01 0.037,0.015 0.029,0.014 0.061,0.023 0.09,0.038 0.136,0.065 0.279,0.118 0.419,0.175 0.131,0.054 0.258,0.117 0.392,0.164 0.006,0.002 0.011,0.005 0.017,0.007 0.022,0.008 0.042,0.019 0.065,0.027 0.028,0.01 0.055,0.021 0.083,0.03 0.011,0.003 0.022,0.005 0.033,0.008 0.035,0.011 0.073,0.016 0.108,0.026 0.013,0.004 0.028,0.006 0.042,0.01 0.188,0.057 0.383,0.098 0.577,0.141 0.076,0.017 0.149,0.041 0.226,0.055 0.011,0.002 0.021,0.006 0.033,0.008 0.025,0.005 0.048,0.014 0.074,0.018 0.041,0.007 0.081,0.02 0.123,0.026 0.033,0.005 0.067,0.003 0.1,0.008 0.006,0.001 0.011,0 0.017,0.001 0.002,0 0.003,0 0.005,0 0.369,0.053 0.743,0.09 1.124,0.09 0.002,0 0.004,0 0.007,0 v 0 c 0.001,0 0.002,0 0.002,0 0,0 10e-4,0 10e-4,0 0.001,0 0.002,0 0.003,0 0.382,0 0.756,-0.037 1.126,-0.09 10e-4,0 0.003,0 0.004,0 0.006,-0.001 0.012,0 0.018,-0.001 0.033,-0.005 0.068,-0.003 0.101,-0.008 0.042,-0.007 0.082,-0.019 0.124,-0.026 0.025,-0.004 0.048,-0.013 0.073,-0.018 0.011,-0.002 0.021,-0.006 0.032,-0.008 0.078,-0.015 0.153,-0.039 0.231,-0.056 0.191,-0.042 0.383,-0.083 0.57,-0.139 0.013,-0.004 0.026,-0.005 0.039,-0.009 0.037,-0.011 0.075,-0.016 0.112,-0.027 0.011,-0.004 0.023,-0.005 0.034,-0.008 0.029,-0.009 0.057,-0.021 0.085,-0.031 0.022,-0.008 0.042,-0.019 0.064,-0.027 0.006,-0.002 0.011,-0.005 0.017,-0.007 0.142,-0.05 0.276,-0.116 0.415,-0.173 0.129,-0.054 0.261,-0.102 0.387,-0.162 0.031,-0.015 0.064,-0.024 0.094,-0.039 0.012,-0.006 0.026,-0.01 0.038,-0.016 0.017,-0.008 0.035,-0.013 0.052,-0.022 0.023,-0.012 0.045,-0.026 0.067,-0.037 0,0 10e-4,0 10e-4,-10e-4 0.037,-0.019 0.07,-0.046 0.107,-0.066 0.258,-0.14 0.508,-0.293 0.749,-0.46 0.019,-0.013 0.041,-0.023 0.061,-0.037 0.005,-0.004 0.011,-0.006 0.016,-0.01 0.023,-0.017 0.05,-0.028 0.073,-0.045 l 156.44,-113.65 c 7.124,-5.182 10.081,-14.302 7.356,-22.694 z m -67.32,-155.581 30.68,94.456 h -61.36 z m 25.307,110.428 -12.519,16.041 -92.334,118.307 43.677,-134.348 z M 285.428,430.707 c 0,0 0,0 0,0 0.008,0.024 0.021,0.046 0.029,0.071 -0.008,-0.025 -0.021,-0.047 -0.029,-0.071 z M 271.42,387.558 166.624,253.202 v 0 h 61.18 z m -79.545,-244.785 30.737,94.457 h -61.36 z m -50.571,165.36 c -1.516,-1.103 -2.144,-3.05 -1.563,-4.838 l 13.466,-41.325 98.67,126.502 z m 146.749,126.356 c -0.031,-0.025 -0.061,-0.052 -0.091,-0.078 -0.006,-0.005 -0.012,-0.012 -0.019,-0.017 -0.06,-0.05 -0.119,-0.101 -0.177,-0.153 -0.114,-0.099 -0.226,-0.2 -0.333,-0.306 0.009,0.008 0.019,0.015 0.028,0.023 0.012,0.011 0.025,0.02 0.037,0.031 0.229,0.219 0.47,0.425 0.722,0.615 0.003,0.002 0.005,0.005 0.008,0.007 0.012,0.009 0.022,0.02 0.034,0.03 -0.069,-0.05 -0.141,-0.098 -0.209,-0.152 z m 4.975,-32.097 -25.665,-79.059 -22.766,-70.131 h 96.933 z m 5.253,31.849 c -0.06,0.052 -0.118,0.104 -0.179,0.154 -0.007,0.006 -0.014,0.013 -0.021,0.019 -0.031,0.025 -0.06,0.052 -0.09,0.077 -0.066,0.053 -0.138,0.101 -0.207,0.152 0.012,-0.009 0.022,-0.021 0.035,-0.029 0.002,-0.002 0.004,-0.004 0.006,-0.006 0.252,-0.19 0.492,-0.394 0.719,-0.613 0.009,-0.009 0.02,-0.016 0.029,-0.024 0.012,-0.011 0.025,-0.02 0.036,-0.031 -0.106,0.103 -0.217,0.203 -0.328,0.301 z M 444.766,308.13 334.209,388.447 432.912,261.98 l 13.412,41.307 c 0.582,1.796 -0.045,3.743 -1.558,4.843 z"
+   class="st2" />
+</g>
+</svg>

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jazzy
-  VERSION = '0.13.7'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.14.2' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/highlighter.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
+
 require 'rouge'
 
 module Jazzy
   # This module helps highlight code
   module Highlighter
-    SWIFT = 'swift'.freeze
-    OBJC = 'objective_c'.freeze
+    SWIFT = 'swift'
+    OBJC = 'objective_c'
 
     class Formatter < Rouge::Formatters::HTML
       def initialize(language)
@@ -12,7 +14,7 @@ module Jazzy
         super()
       end
 
-      def stream(tokens, &b)
+      def stream(tokens, &block)
         yield "<pre class=\"highlight #{@language}\"><code>"
         super
         yield "</code></pre>\n"

data/lib/jazzy/jazzy_markdown.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'redcarpet'
 require 'rouge'
 require 'rouge/plugins/redcarpet'
@@ -38,10 +40,12 @@ module Jazzy
         mapped = map_footnote(num)
         "\n<li><div class='footnote-def' id=\"fn#{mapped}\">" +
           text.sub(%r{(?=</p>)},
-                   "&nbsp;<a href=\"#fnref#{mapped}\">&#8617;</a></div></li>")
+                   "&nbsp;<a href=\"#fnref#{mapped}\">&#8617;</a>") +
+          '</div></li>'
       end
     end
 
+    # rubocop:disable Metrics/ClassLength
     class JazzyHTML < Redcarpet::Render::HTML
       include Redcarpet::Render::SmartyPants
       include Rouge::Plugins::Redcarpet
@@ -51,24 +55,27 @@ module Jazzy
 
       def header(text, header_level)
         text_slug = text.gsub(/[^[[:word:]]]+/, '-')
-                        .downcase
-                        .sub(/^-/, '')
-                        .sub(/-$/, '')
+          .downcase
+          .sub(/^-/, '')
+          .sub(/-$/, '')
 
         "<h#{header_level} id='#{text_slug}' class='heading'>" \
           "#{text}" \
-        "</h#{header_level}>\n"
+          "</h#{header_level}>\n"
       end
 
       def codespan(text)
-        if /^\$\$(.*)\$\$$/m =~ text
-          o = ["<div class='math m-block'>", Regexp.last_match[1], '</div>']
+        case text
+        when /^\$\$(.*)\$\$$/m
+          o = ["</p><div class='math m-block'>",
+               Regexp.last_match[1],
+               '</div><p>']
           Markdown.has_math = true
-        elsif /^\$(.*)\$$/m =~ text
+        when /^\$(.*)\$$/m
           o = ["<span class='math m-inline'>", Regexp.last_match[1], '</span>']
           Markdown.has_math = true
         else
-          o = ['<code>', text, '</code>']
+          o = ['<code>', text.to_s, '</code>']
         end
 
         o[0] + CGI.escapeHTML(o[1]) + o[2]
@@ -115,10 +122,10 @@ module Jazzy
         # any one of our special list types
         (#{SPECIAL_LIST_TYPES.map(&Regexp.method(:escape)).join('|')})
         [\s:] # followed by either a space or a colon
-      }ix
+        }ix.freeze
 
       ELIDED_LI_TOKEN =
-        '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'.freeze
+        '7wNVzLB0OYPL2eGlPKu8q4vITltqh0Y6DPZf659TPMAeYh49o'
 
       def list_item(text, _list_type)
         if text =~ SPECIAL_LIST_TYPE_REGEX
@@ -126,30 +133,58 @@ module Jazzy
           if UNIQUELY_HANDLED_CALLOUTS.include? type.downcase
             return ELIDED_LI_TOKEN
           end
-          return render_aside(type, text.sub(/#{Regexp.escape(type)}:\s+/, ''))
+
+          return render_list_aside(type,
+                                   text.sub(/#{Regexp.escape(type)}:\s+/, ''))
         end
-        str = '<li>'
-        str << text.strip
-        str << "</li>\n"
+        "<li>#{text.strip}</li>\n"
+      end
+
+      def render_list_aside(type, text)
+        "</ul>#{render_aside(type, text).chomp}<ul>\n"
       end
 
       def render_aside(type, text)
         <<-HTML
-</ul><div class="aside aside-#{type.underscore.tr('_', '-')}">
+<div class="aside aside-#{type.underscore.tr('_', '-')}">
     <p class="aside-title">#{type.underscore.humanize}</p>
     #{text}
-</div><ul>
+</div>
         HTML
       end
 
       def list(text, list_type)
         elided = text.gsub!(ELIDED_LI_TOKEN, '')
         return if text =~ /\A\s*\Z/ && elided
-        str = "\n"
-        str << (list_type == :ordered ? "<ol>\n" : "<ul>\n")
-        str << text
-        str << (list_type == :ordered ? "</ol>\n" : "</ul>\n")
-        str.gsub(%r{\n?<ul>\n<\/ul>}, '')
+
+        tag = list_type == :ordered ? 'ol' : 'ul'
+        "\n<#{tag}>\n#{text}</#{tag}>\n"
+          .gsub(%r{\n?<ul>\n?</ul>}, '')
+      end
+
+      # List from
+      # https://developer.apple.com/documentation/xcode/formatting-your-documentation-content#Add-Notes-and-Other-Asides
+      DOCC_CALLOUTS = %w[note
+                         important
+                         warning
+                         tip
+                         experiment].freeze
+
+      DOCC_CALLOUT_REGEX = %r{
+        \A\s* # optional leading spaces
+        (?:<p>\s*)? # optional opening p tag
+        # any one of the callout names
+        (#{DOCC_CALLOUTS.map(&Regexp.method(:escape)).join('|')})
+        : # followed directly by a colon
+      }ix.freeze
+
+      def block_quote(html)
+        if html =~ DOCC_CALLOUT_REGEX
+          type = Regexp.last_match[1]
+          render_aside(type, html.sub(/#{Regexp.escape(type)}:\s*/, ''))
+        else
+          "\n<blockquote>\n#{html}</blockquote>\n"
+        end
       end
 
       def block_code(code, language)
@@ -160,6 +195,7 @@ module Jazzy
         Highlighter::Formatter.new(lexer.tag)
       end
     end
+    # rubocop:enable Metrics/ClassLength
 
     REDCARPET_OPTIONS = {
       autolink: true,
@@ -182,22 +218,22 @@ module Jazzy
         super
       end
 
-      INTRO_PAT = '\A(?<intro>\s*(<p>\s*)?)'.freeze
-      OUTRO_PAT = '(?<outro>.*)\z'.freeze
+      INTRO_PAT = '\A(?<intro>\s*(<p>\s*)?)'
+      OUTRO_PAT = '(?<outro>.*)\z'
 
-      RETURNS_REGEX = /#{INTRO_PAT}returns:#{OUTRO_PAT}/im
+      RETURNS_REGEX = /#{INTRO_PAT}returns:#{OUTRO_PAT}/im.freeze
 
-      IDENT_PAT = '(?<param>\S+)'.freeze
+      IDENT_PAT = '(?<param>\S+)'
 
       # Param formats: normal swift, objc via sourcekitten, and
       # possibly inside 'Parameters:'
-      PARAM_PAT1 = "(parameter +#{IDENT_PAT}\\s*:)".freeze
-      PARAM_PAT2 = "(parameter:\\s*#{IDENT_PAT}\\s+)".freeze
-      PARAM_PAT3 = "(#{IDENT_PAT}\\s*:)".freeze
+      PARAM_PAT1 = "(parameter +#{IDENT_PAT}\\s*:)"
+      PARAM_PAT2 = "(parameter:\\s*#{IDENT_PAT}\\s+)"
+      PARAM_PAT3 = "(#{IDENT_PAT}\\s*:)"
 
-      PARAM_PAT = "(?:#{PARAM_PAT1}|#{PARAM_PAT2}|#{PARAM_PAT3})".freeze
+      PARAM_PAT = "(?:#{PARAM_PAT1}|#{PARAM_PAT2}|#{PARAM_PAT3})"
 
-      PARAM_REGEX = /#{INTRO_PAT}#{PARAM_PAT}#{OUTRO_PAT}/im
+      PARAM_REGEX = /#{INTRO_PAT}#{PARAM_PAT}#{OUTRO_PAT}/im.freeze
 
       def list_item(text, _list_type)
         if text =~ RETURNS_REGEX
@@ -225,12 +261,19 @@ module Jazzy
       @markdown ||= Redcarpet::Markdown.new(renderer, REDCARPET_OPTIONS)
     end
 
+    # Produces <p>-delimited block content
     def self.render(markdown_text, default_language = nil)
       renderer.reset
       renderer.default_language = default_language
       markdown.render(markdown_text)
     end
 
+    # Produces <span>-delimited inline content
+    def self.render_inline(markdown_text, default_language = nil)
+      render(markdown_text, default_language)
+        .sub(%r{^<p>(.*)</p>$}, '<span>\1</span>')
+    end
+
     def self.rendered_returns
       renderer.returns
     end
@@ -242,7 +285,7 @@ module Jazzy
     class JazzyCopyright < Redcarpet::Render::HTML
       def link(link, _title, content)
         %(<a class="link" href="#{link}" target="_blank" \
-rel="external">#{content}</a>)
+rel="external noopener">#{content}</a>)
       end
     end