jazzy 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8b0a6f32e8d7182725eafedb4ec488e382de192af903fb42ee9d7cd3c7396c3
-  data.tar.gz: 1b2dbf01dae14692d0a04a1912f71d98cc44d2397fe81280df0d072089b3ad4b
+  metadata.gz: d55202d57dfdb0b3aad10b90f122d34e10a529bf73dde92ce2d0063473c011fe
+  data.tar.gz: 221dd32f5dac077431fe1d449b857966b2b9dcfc8a5f4cd0cefd61e1862558c9
 SHA512:
-  metadata.gz: 04ef74edf753cb424bfe2b9f8bdc7860b3d9072e91a5be60a7db38981d705cc595286a33d805482129746b4ee6626ef5852cbbf13e428d0e0f7fcd99310adf14
-  data.tar.gz: 8b038aaabd0516983b87d80841e1dc490b35e6493cae241193d07b09c946f8f47dd0b7b84bd20300fd382d522ad6ca3104fb2478c9eb6ab764afb5a6840014b4
+  metadata.gz: cf1b7616ead246ea0e45a0c1e3148fc8cf3a04600c295c5bec0c7b5cff530296b9deb50f6b9c429940c1bf12dce036d4863038e55b3f892e748e5e99e7f3fc65
+  data.tar.gz: e7725d323d9550f97f27a6bd2e0c89d674cda5d4199dc6433e38f7b78e01f58388d8af8842c28293abb9ce4434068e24fbf1483941e2ab771787db7220dd788a

data/CHANGELOG.md

@@ -1,3 +1,36 @@
+## 0.13.0
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Add section headings for members added by Swift conditional conformances.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#717](https://github.com/realm/jazzy/issues/717)
+
+* Parse markdown in MARK comments, make the html available to themes via
+  `name_html` mustache tag key for section headings.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+* Include protocol conformances added by extensions in Swift docs.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Bug Fixes
+
+* Render bullet lists correctly when followed by a callout.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#785](https://github.com/realm/jazzy/issues/785)
+
+* Render markup of text inside double quotes.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#992](https://github.com/realm/jazzy/issues/992)
+
+* Fix `sourcekitten_sourcefile` used from config file.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1137](https://github.com/realm/jazzy/issues/1137)
+
 ## 0.12.0
 
 ##### Breaking

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.12.0)
+    jazzy (0.13.0)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
       open4
@@ -14,7 +14,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    CFPropertyList (3.0.1)
+    CFPropertyList (3.0.2)
     activesupport (4.2.11.1)
       i18n (~> 0.7)
       minitest (~> 5.1)
@@ -62,7 +62,7 @@ GEM
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
     cocoapods-deintegrate (1.0.4)
-    cocoapods-downloader (1.2.2)
+    cocoapods-downloader (1.3.0)
     cocoapods-plugins (1.0.0)
       nap
     cocoapods-search (1.0.0)
@@ -93,11 +93,11 @@ GEM
       terminal-table (~> 1)
     diffy (3.3.0)
     escape (0.0.4)
-    faraday (0.17.0)
+    faraday (0.17.1)
       multipart-post (>= 1.2, < 3)
     faraday-http-cache (2.0.0)
       faraday (~> 0.8)
-    ffi (1.11.1)
+    ffi (1.11.3)
     fourflusher (2.3.1)
     fuzzy_match (2.0.4)
     gh_inspector (1.1.3)
@@ -111,15 +111,13 @@ GEM
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liferaft (0.0.6)
-    metaclass (0.0.4)
     minitest (5.13.0)
-    mocha (1.9.0)
-      metaclass (~> 0.0.1)
+    mocha (1.10.1)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
     molinillo (0.6.6)
     multipart-post (2.1.1)
-    mustache (1.1.0)
+    mustache (1.1.1)
     nanaimo (0.2.6)
     nap (1.1.0)
     netrc (0.11.0)
@@ -127,7 +125,7 @@ GEM
     octokit (4.14.0)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
-    parallel (1.18.0)
+    parallel (1.19.1)
     parser (2.6.5.0)
       ast (~> 2.4.0)
     powerpack (0.1.2)
@@ -138,7 +136,7 @@ GEM
       rake
     rake (10.5.0)
     redcarpet (3.5.0)
-    rouge (3.12.0)
+    rouge (3.13.0)
     rubocop (0.49.0)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)

data/lib/jazzy/config.rb

@@ -176,7 +176,7 @@ module Jazzy
       command_line: ['-s', '--sourcekitten-sourcefile filepath1,…filepathN',
                      Array],
       description: 'File(s) generated from sourcekitten output to parse',
-      parse: ->(paths) { paths.map { |path| expand_path(path) } }
+      parse: ->(paths) { [paths].flatten.map { |path| expand_path(path) } }
 
     config_attr :source_directory,
       command_line: '--source-directory DIRPATH',

data/lib/jazzy/doc_builder.rb

@@ -350,9 +350,10 @@ module Jazzy
     end
     # rubocop:enable Metrics/MethodLength
 
-    def self.make_task(mark, uid, items)
+    def self.make_task(mark, uid, items, doc_model)
       {
         name: mark.name,
+        name_html: (render(doc_model, mark.name) if mark.name),
         uid: URI.encode(uid),
         items: items,
         pre_separator: mark.has_start_dash,
@@ -376,7 +377,7 @@ module Jazzy
         else
           mark_names_counts[uid] = 1
         end
-        make_task(mark, uid, items)
+        make_task(mark, uid, items, mark_children.first)
       end
     end
 

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.12.0'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.13.0'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/jazzy_markdown.rb

@@ -82,21 +82,21 @@ module Jazzy
 
       def render_aside(type, text)
         <<-HTML
-<div class="aside aside-#{type.underscore.tr('_', '-')}">
+</ul><div class="aside aside-#{type.underscore.tr('_', '-')}">
     <p class="aside-title">#{type.underscore.humanize}</p>
     #{text}
-</div>
+</div><ul>
         HTML
       end
 
       def list(text, list_type)
         elided = text.gsub!(ELIDED_LI_TOKEN, '')
         return if text =~ /\A\s*\Z/ && elided
-        return text if text =~ /class="aside-title"/
         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>}, '')
       end
 
       def block_code(code, language)
@@ -112,7 +112,6 @@ module Jazzy
       autolink: true,
       fenced_code_blocks: true,
       no_intra_emphasis: true,
-      quote: true,
       strikethrough: true,
       space_after_headers: false,
       tables: true,

data/lib/jazzy/source_declaration.rb

@@ -130,6 +130,8 @@ module Jazzy
     attr_accessor :deprecation_message
     attr_accessor :unavailable
     attr_accessor :unavailable_message
+    attr_accessor :generic_requirements
+    attr_accessor :inherited_types
 
     def usage_discouraged?
       unavailable || deprecated
@@ -139,6 +141,36 @@ module Jazzy
       CGI.unescape(url)
     end
 
+    def constrained_extension?
+      type.swift_extension? &&
+        generic_requirements
+    end
+
+    def mark_for_children
+      if constrained_extension?
+        SourceMark.new_generic_requirements(generic_requirements)
+      else
+        SourceMark.new
+      end
+    end
+
+    def inherited_types?
+      inherited_types &&
+        !inherited_types.empty?
+    end
+
+    # Is there at least one inherited type that is not in the given list?
+    def other_inherited_types?(unwanted)
+      return false unless inherited_types?
+      inherited_types.any? { |t| !unwanted.include?(t) }
+    end
+
+    # SourceKit only sets modulename for imported modules
+    def type_from_doc_module?
+      !type.extension? ||
+        (swift? && usr && modulename.nil?)
+    end
+
     def alternative_abstract
       if file = alternative_abstract_file
         Pathname(file).read

data/lib/jazzy/source_declaration/type.rb

@@ -114,6 +114,10 @@ module Jazzy
         kind == 'source.lang.swift.decl.protocol'
       end
 
+      def swift_typealias?
+        kind == 'source.lang.swift.decl.typealias'
+      end
+
       def param?
         # SourceKit strangely categorizes initializer parameters as local
         # variables, so both kinds represent a parameter in jazzy.

data/lib/jazzy/source_mark.rb

@@ -28,6 +28,12 @@ module Jazzy
       self.name = mark_string[start_index..end_index]
     end
 
+    def self.new_generic_requirements(requirements)
+      marked_up = requirements.gsub(/\b([^=:]\S*)\b/, '`\1`')
+      text = "Available where #{marked_up}"
+      new(text)
+    end
+
     def empty?
       !name && !has_start_dash && !has_end_dash
     end
@@ -37,5 +43,10 @@ module Jazzy
       self.has_start_dash = other.has_start_dash
       self.has_end_dash = other.has_end_dash
     end
+
+    # Can we merge the contents of another mark into our own?
+    def can_merge?(other)
+      other.empty? || other.name == name
+    end
   end
 end

data/lib/jazzy/sourcekitten.rb

@@ -124,6 +124,18 @@ module Jazzy
       end
     end
 
+    # Merge consecutive sections with the same mark into one section
+    def self.merge_consecutive_marks(docs)
+      prev_mark = nil
+      docs.each do |doc|
+        if prev_mark && prev_mark.can_merge?(doc.mark)
+          doc.mark = prev_mark
+        end
+        prev_mark = doc.mark
+        merge_consecutive_marks(doc.children)
+      end
+    end
+
     def self.sanitize_filename(doc)
       unsafe_filename = doc.url_name || doc.name
       sanitzation_enabled = Config.instance.use_safe_filenames
@@ -289,21 +301,29 @@ module Jazzy
         return false
       end
 
-      # Document extensions & enum elements, since we can't tell their ACL.
+      # Document enum elements, since we can't tell their ACL.
       return true if type.swift_enum_element?
-      if type.swift_extension?
-        return Array(doc['key.substructure']).any? do |subdoc|
-          subtype = SourceDeclaration::Type.new(subdoc['key.kind'])
-          !subtype.mark? && should_document?(subdoc)
-        end
-      end
+      # Document extensions if they might have parts covered by the ACL.
+      return should_document_swift_extension?(doc) if type.swift_extension?
 
       acl_ok = SourceDeclaration::AccessControlLevel.from_doc(doc) >= @min_acl
-      acl_ok.tap { @stats.add_acl_skipped unless acl_ok }
+      unless acl_ok
+        @stats.add_acl_skipped
+        @inaccessible_protocols.append(doc['key.name']) if type.swift_protocol?
+      end
+      acl_ok
     end
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/PerceivedComplexity
 
+    def self.should_document_swift_extension?(doc)
+      doc['key.inheritedtypes'] ||
+        Array(doc['key.substructure']).any? do |subdoc|
+          subtype = SourceDeclaration::Type.new(subdoc['key.kind'])
+          !subtype.mark? && should_document?(subdoc)
+        end
+    end
+
     def self.should_mark_undocumented(filepath)
       source_directory = Config.instance.source_directory.to_s
       (filepath || '').start_with?(source_directory)
@@ -467,14 +487,10 @@ module Jazzy
     end
 
     def self.make_substructure(doc, declaration)
-      declaration.children = if doc['key.substructure']
-                               make_source_declarations(
-                                 doc['key.substructure'],
-                                 declaration,
-                               )
-                             else
-                               []
-                             end
+      return [] unless subdocs = doc['key.substructure']
+      make_source_declarations(subdocs,
+                               declaration,
+                               declaration.mark_for_children)
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -531,10 +547,17 @@ module Jazzy
         declaration.end_line = doc['key.parsed_scope.end']
         declaration.deprecated = doc['key.always_deprecated']
         declaration.unavailable = doc['key.always_unavailable']
+        declaration.generic_requirements =
+          find_generic_requirements(doc['key.parsed_declaration'])
+        inherited_types = doc['key.inheritedtypes'] || []
+        declaration.inherited_types =
+          inherited_types.map { |type| type['key.name'] }.compact
 
         next unless make_doc_info(doc, declaration)
-        make_substructure(doc, declaration)
-        next if declaration.type.extension? && declaration.children.empty?
+        declaration.children = make_substructure(doc, declaration)
+        next if declaration.type.extension? &&
+                declaration.children.empty? &&
+                !declaration.inherited_types?
         declarations << declaration
       end
       declarations
@@ -543,6 +566,12 @@ module Jazzy
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/MethodLength
 
+    def self.find_generic_requirements(parsed_declaration)
+      parsed_declaration =~ /\bwhere\s+(.*)$/m
+      return nil unless Regexp.last_match
+      Regexp.last_match[1].gsub(/\s+/, ' ')
+    end
+
     # Expands extensions of nested types declared at the top level into
     # a tree so they can be deduplicated properly
     def self.expand_extensions(decls)
@@ -566,6 +595,7 @@ module Jazzy
       SourceDeclaration.new.tap do |decl|
         make_default_doc_info(decl)
         decl.name = name
+        decl.modulename = extension.modulename
         decl.type = extension.type
         decl.mark = extension.mark
         decl.usr = candidates.first.usr unless candidates.empty?
@@ -588,10 +618,10 @@ module Jazzy
                          .group_by { |d| deduplication_key(d, declarations) }
                          .values
 
-      duplicate_groups.map do |group|
+      duplicate_groups.flat_map do |group|
         # Put extended type (if present) before extensions
         merge_declarations(group)
-      end
+      end.compact
     end
 
     # Returns true if an Objective-C declaration is mergeable.
@@ -601,13 +631,21 @@ module Jazzy
             && name_match(decl.objc_category_name[0], root_decls))
     end
 
+    # Returns if a Swift declaration is mergeable.
+    # Start off merging in typealiases to help understand extensions.
+    def self.mergeable_swift?(decl)
+      decl.type.swift_extensible? ||
+        decl.type.swift_extension? ||
+        decl.type.swift_typealias?
+    end
+
     # Two declarations get merged if they have the same deduplication key.
     def self.deduplication_key(decl, root_decls)
       # Swift extension of objc class
       if decl.swift_objc_extension?
         [decl.swift_extension_objc_name, :objc_class_and_categories]
       # Swift type or Swift extension of Swift type
-      elsif decl.type.swift_extensible? || decl.type.swift_extension?
+      elsif mergeable_swift?(decl)
         [decl.usr, decl.name]
       # Objc categories and classes
       elsif mergeable_objc?(decl, root_decls)
@@ -633,17 +671,36 @@ module Jazzy
       end
       typedecl = typedecls.first
 
+      extensions = reject_inaccessible_extensions(typedecl, extensions)
+
       if typedecl
         if typedecl.type.swift_protocol?
-          merge_default_implementations_into_protocol(typedecl, extensions)
-          mark_members_from_protocol_extension(extensions)
+          mark_and_merge_protocol_extensions(typedecl, extensions)
           extensions.reject! { |ext| ext.children.empty? }
         end
 
-        merge_declaration_marks(typedecl, extensions)
+        merge_objc_declaration_marks(typedecl, extensions)
       end
 
-      decls = typedecls + extensions
+      # Keep type-aliases separate from any extensions
+      if typedecl && typedecl.type.swift_typealias?
+        [merge_type_and_extensions(typedecls, []),
+         merge_type_and_extensions([], extensions)]
+      else
+        merge_type_and_extensions(typedecls, extensions)
+      end
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    def self.merge_type_and_extensions(typedecls, extensions)
+      # Constrained extensions at the end
+      constrained, regular_exts = extensions.partition(&:constrained_extension?)
+      decls = typedecls + regular_exts + constrained
+      return nil if decls.empty?
+
+      move_merged_extension_marks(decls)
+      merge_code_declaration(decls)
+
       decls.first.tap do |merged|
         merged.children = deduplicate_declarations(
           decls.flat_map(&:children).uniq,
@@ -653,58 +710,112 @@ module Jazzy
         end
       end
     end
-    # rubocop:enable Metrics/MethodLength
 
+    # Now we know all the public types and all the private protocols,
+    # reject extensions that add public protocols to private types
+    # or add private protocols to public types.
+    def self.reject_inaccessible_extensions(typedecl, extensions)
+      swift_exts, objc_exts = extensions.partition(&:swift?)
+
+      # Reject extensions that are just conformances to private protocols
+      unwanted_exts, wanted_exts = swift_exts.partition do |ext|
+        ext.children.empty? &&
+          !ext.other_inherited_types?(@inaccessible_protocols)
+      end
+
+      # Given extensions of a type from this module, without the
+      # type itself, the type must be private and the extensions
+      # should be rejected.
+      if !typedecl &&
+         wanted_exts.first &&
+         wanted_exts.first.type_from_doc_module?
+        unwanted_exts += wanted_exts
+        wanted_exts = []
+      end
+
+      # Don't tell the user to document them
+      unwanted_exts.each { |e| @stats.remove_undocumented(e) }
+
+      objc_exts + wanted_exts
+    end
+
+    # Protocol extensions.
+    #
     # If any of the extensions provide default implementations for methods in
     # the given protocol, merge those members into the protocol doc instead of
     # keeping them on the extension. These get a “Default implementation”
-    # annotation in the generated docs.
-    def self.merge_default_implementations_into_protocol(protocol, extensions)
-      protocol.children.each do |proto_method|
-        extensions.each do |ext|
-          defaults, ext.children = ext.children.partition do |ext_member|
-            ext_member.name == proto_method.name
+    # annotation in the generated docs.  Default implementations added by
+    # conditional extensions are annotated but listed separately.
+    #
+    # Protocol methods provided only in an extension and not in the protocol
+    # itself are a special beast: they do not use dynamic dispatch. These get an
+    # “Extension method” annotation in the generated docs.
+    def self.mark_and_merge_protocol_extensions(protocol, extensions)
+      extensions.each do |ext|
+        ext.children = ext.children.select do |ext_member|
+          proto_member = protocol.children.find do |p|
+            p.name == ext_member.name && p.type == ext_member.type
+          end
+
+          # Extension-only method, keep.
+          unless proto_member
+            ext_member.from_protocol_extension = true
+            next true
           end
-          unless defaults.empty?
-            proto_method.default_impl_abstract =
-              defaults.flat_map { |d| [d.abstract, d.discussion] }.join
+
+          # Default impl but constrained, mark and keep.
+          if ext.constrained_extension?
+            ext_member.default_impl_abstract = ext_member.abstract
+            ext_member.abstract = nil
+            next true
           end
+
+          # Default impl for all users, merge.
+          proto_member.default_impl_abstract = ext_member.abstract
+          next false
         end
       end
     end
 
-    # Protocol methods provided only in an extension and not in the protocol
-    # itself are a special beast: they do not use dynamic dispatch. These get an
-    # “Extension method” annotation in the generated docs.
-    def self.mark_members_from_protocol_extension(extensions)
+    # Mark children merged from categories with the name of category
+    # (unless they already have a mark)
+    def self.merge_objc_declaration_marks(typedecl, extensions)
+      return unless typedecl.type.objc_class?
       extensions.each do |ext|
-        ext.children.each do |ext_member|
-          ext_member.from_protocol_extension = true
-        end
+        _, category_name = ext.objc_category_name
+        ext.children.each { |c| c.mark.name ||= category_name }
       end
     end
 
-    # Customize marks associated with to-be-merged declarations
-    def self.merge_declaration_marks(typedecl, extensions)
-      if typedecl.type.objc_class?
-        # Mark children merged from categories with the name of category
-        # (unless they already have a mark)
-        extensions.each do |ext|
-          _, category_name = ext.objc_category_name
-          ext.children.each { |c| c.mark.name ||= category_name }
-        end
-      else
-        # If the Swift extension has a mark and the first child doesn't
-        # then copy the mark contents down so it still shows up.
-        extensions.each do |ext|
-          child = ext.children.first
-          if child && child.mark.empty?
-            child.mark.copy(ext.mark)
-          end
+    # For each extension to be merged, move any MARK from the extension
+    # declaration down to the extension contents so it still shows up.
+    def self.move_merged_extension_marks(decls)
+      return unless to_be_merged = decls[1..-1]
+      to_be_merged.each do |ext|
+        child = ext.children.first
+        if child && child.mark.empty?
+          child.mark.copy(ext.mark)
         end
       end
     end
 
+    # Merge useful information added by extensions into the main
+    # declaration: public protocol conformances and, for top-level extensions,
+    # further conditional extensions of the same type.
+    def self.merge_code_declaration(decls)
+      first = decls.first
+
+      declarations = decls[1..-1].select do |decl|
+        decl.type.swift_extension? &&
+          (decl.other_inherited_types?(@inaccessible_protocols) ||
+            (first.type.swift_extension? && decl.constrained_extension?))
+      end.map(&:declaration)
+
+      unless declarations.empty?
+        first.declaration = declarations.prepend(first.declaration).uniq.join
+      end
+    end
+
     # Apply filtering based on the "included" and "excluded" flags.
     def self.filter_files(json)
       json = filter_included_files(json) if Config.instance.included_files.any?
@@ -860,6 +971,7 @@ module Jazzy
       @min_acl = min_acl
       @skip_undocumented = skip_undocumented
       @stats = Stats.new
+      @inaccessible_protocols = []
       sourcekitten_json = filter_files(JSON.parse(sourcekitten_output).flatten)
       docs = make_source_declarations(sourcekitten_json).concat inject_docs
       docs = expand_extensions(docs)
@@ -870,6 +982,7 @@ module Jazzy
       docs = docs.reject { |doc| doc.type.swift_enum_element? }
       ungrouped_docs = docs
       docs = group_docs(docs)
+      merge_consecutive_marks(docs)
       make_doc_urls(docs)
       autolink(docs, ungrouped_docs)
       [docs, @stats]

data/lib/jazzy/stats.rb

@@ -18,6 +18,10 @@ module Jazzy
       @undocumented_decls << decl
     end
 
+    def remove_undocumented(decl)
+      @undocumented_decls.delete(decl)
+    end
+
     def acl_included
       documented + undocumented
     end

data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss

@@ -152,7 +152,7 @@ header {
   background-color: $bg_color;
   position: fixed;
   width: 100%;
-  z-index: 1;
+  z-index: 2;
   img {
     padding-right: 6px;
     vertical-align: -4px;
@@ -177,7 +177,7 @@ header {
   padding-top: $breadcrumb_padding_top;
   position: fixed;
   width: 100%;
-  z-index: 1;
+  z-index: 2;
   margin-top: $header_height;
   #carat {
     height: 10px;
@@ -270,6 +270,17 @@ header {
       margin: -$content_top_offset 0 0;
     }
   }
+  .section-name {
+    p {
+       margin-bottom: inherit;
+       line-height: inherit;
+    }
+    code {
+      background-color: inherit;
+      padding: inherit;
+      color: inherit;
+    }
+  }
 }
 
 .section {
@@ -317,6 +328,29 @@ header {
   }
 }
 
+.section-name-container {
+  position: relative;
+  display: inline-block;
+
+  .section-name-link {
+    position: absolute;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    right: 0;
+    margin-bottom: 0;
+  }
+
+  .section-name {
+    position: relative;
+    pointer-events: none;
+    z-index: 1;
+    a {
+      pointer-events: auto;
+    }
+  }
+}
+
 .item {
   padding-top: 8px;
   width: 100%;

data/lib/jazzy/themes/apple/templates/task.mustache

@@ -3,9 +3,10 @@
   <div class="task-name-container">
     <a name="/{{uid}}"></a>
     <a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
-    <a href="#/{{uid}}">
-      <h3 class="section-name">{{name}}</h3>
-    </a>
+    <div class="section-name-container">
+      <a class="section-name-link" href="#/{{uid}}"></a>
+      <h3 class="section-name">{{{name_html}}}</h3>
+    </div>
   </div>
   {{/name}}
   <ul>

data/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss

@@ -201,13 +201,15 @@ code {
   font-family: $code_font;
 }
 
-p, li {
-  > code {
-    background: $code_bg_color;
-    padding: .2em;
-    &:before, &:after {
-      letter-spacing: -.2em;
-      content: "\00a0";
+.item-container, .top-matter {
+  p, li {
+    > code {
+      background: $code_bg_color;
+      padding: .2em;
+      &:before, &:after {
+        letter-spacing: -.2em;
+        content: "\00a0";
+      }
     }
   }
 }
@@ -367,6 +369,10 @@ pre code {
 .section-name {
   color: #666;
   display: block;
+
+  p {
+    margin-bottom: inherit;
+  }
 }
 
 .declaration .highlight {
@@ -394,6 +400,28 @@ pre code {
   }
 }
 
+.section-name-container {
+  position: relative;
+
+  .section-name-link {
+    position: absolute;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    right: 0;
+    margin-bottom: 0;
+  }
+
+  .section-name {
+    position: relative;
+    pointer-events: none;
+    z-index: 1;
+    a {
+      pointer-events: auto;
+    }
+  }
+}
+
 .item-container {
   padding: 0;
 }

data/lib/jazzy/themes/fullwidth/templates/doc.mustache

@@ -35,7 +35,7 @@
       <article class="main-content">
 
         <section class="section">
-          <div class="section-content">
+          <div class="section-content top-matter">
             {{^hide_name}}<h1>{{name}}</h1>{{/hide_name}}
             {{> deprecation}}
             {{#declaration}}

data/lib/jazzy/themes/fullwidth/templates/task.mustache

@@ -3,9 +3,10 @@
   <div class="task-name-container">
     <a name="/{{uid}}"></a>
     <a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
-    <a href="#/{{uid}}">
-      <h3 class="section-name">{{name}}</h3>
-    </a>
+    <div class="section-name-container">
+      <a class="section-name-link" href="#/{{uid}}"></a>
+      <h3 class="section-name">{{{name_html}}}</h3>
+    </div>
   </div>
   {{/name}}
   <ul class="item-container">

data/lib/jazzy/themes/jony/assets/css/jazzy.css.scss

@@ -182,7 +182,7 @@ header {
   background-color: $bg_color;
   position: fixed;
   width: 100%;
-  z-index: 2;
+  z-index: 3;
   img {
     padding-right: 6px;
     vertical-align: -4px;
@@ -204,7 +204,7 @@ header {
 #breadcrumbs-container {
   background-color: $bg_color;
   position: fixed;
-  z-index: 1;
+  z-index: 2;
   width: 100%;
 }
 
@@ -310,6 +310,16 @@ header {
       margin: -$content_top_offset 0 0;
     }
   }
+
+  .section-name {
+    p {
+       margin-bottom: inherit;
+       line-height: inherit;
+    }
+    code {
+      color: inherit;
+    }
+  }
 }
 
 .highlight {
@@ -356,6 +366,29 @@ header {
   }
 }
 
+.section-name-container {
+  position: relative;
+  display: inline-block;
+
+  .section-name-link {
+    position: absolute;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    right: 0;
+    margin-bottom: 0;
+  }
+
+  .section-name {
+    position: relative;
+    pointer-events: none;
+    z-index: 1;
+    a {
+      pointer-events: auto;
+    }
+  }
+}
+
 .item {
   padding-top: 8px;
   width: 100%;

data/lib/jazzy/themes/jony/templates/task.mustache

@@ -3,9 +3,10 @@
   <div class="task-name-container">
     <a name="/{{uid}}"></a>
     <a name="//apple_ref/{{language_stub}}/Section/{{name}}" class="dashAnchor"></a>
-    <a href="#/{{uid}}">
-      <h3 class="section-name">{{name}}</h3>
-    </a>
+    <div class="section-name-container">
+      <a class="section-name-link" href="#/{{uid}}"></a>
+      <h3 class="section-name">{{{name_html}}}</h3>
+    </div>
   </div>
   {{/name}}
   <ul>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.12.0
+  version: 0.13.0
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-11-11 00:00:00.000000000 Z
+date: 2019-12-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods