HTML fixes (#1281)

* Misplaced `rel=noopener`, missing alt-text, stray `</div>` * Malformed footnote lists * Malformed math blocks * Badly formed search bar * Malformed section headers
realm · Oct 1, 2021 · dad4695 · dad4695
1 parent 4e1cd27
commit dad4695
Show file tree

Hide file tree

Showing 13 changed files with 39 additions and 25 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -23,7 +23,9 @@
 
 ##### Bug Fixes
 
-* None.
+* Improve HTML5 correctness, all themes.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1280](https://github.com/realm/jazzy/issues/1280)
 
 ## 0.14.0
 

diff --git a/lib/jazzy/doc_builder.rb b/lib/jazzy/doc_builder.rb
@@ -236,6 +236,11 @@ def self.render(doc_model, markdown)
       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|
@@ -379,7 +384,7 @@ def self.render_item(item, source_module)
     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,

diff --git a/lib/jazzy/jazzy_markdown.rb b/lib/jazzy/jazzy_markdown.rb
@@ -40,7 +40,8 @@ def footnote_def(text, num)
         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
 
@@ -66,7 +67,9 @@ def header(text, header_level)
       def codespan(text)
         case text
         when /^\$\$(.*)\$\$$/m
-          o = ["<div class='math m-block'>", Regexp.last_match[1], '</div>']
+          o = ["</p><div class='math m-block'>",
+               Regexp.last_match[1],
+               '</div><p>']
           Markdown.has_math = true
         when /^\$(.*)\$$/m
           o = ["<span class='math m-inline'>", Regexp.last_match[1], '</span>']
@@ -258,12 +261,19 @@ def self.markdown
       @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
@@ -275,7 +285,7 @@ def self.rendered_parameters
     class JazzyCopyright < Redcarpet::Render::HTML
       def link(link, _title, content)
         %(<a class="link" href="#{link}" target="_blank" \
-rel="noopener" rel="external">#{content}</a>)
+rel="external noopener">#{content}</a>)
       end
     end
 

diff --git a/lib/jazzy/themes/apple/templates/doc.mustache b/lib/jazzy/themes/apple/templates/doc.mustache
@@ -29,7 +29,7 @@
     <div class="content-wrapper">
       <p id="breadcrumbs">
         <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
-        <img id="carat" src="{{path_to_root}}img/carat.png" />
+        <img id="carat" src="{{path_to_root}}img/carat.png" alt=""/>
         {{name}} {{kind}} Reference
       </p>
     </div>
@@ -85,5 +85,4 @@
       </article>
     </div>
   </body>
-</div>
 </html>
diff --git a/lib/jazzy/themes/apple/templates/footer.mustache b/lib/jazzy/themes/apple/templates/footer.mustache
@@ -1,4 +1,4 @@
 <section id="footer">
   {{{copyright}}}
-  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="noopener" rel="external">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="noopener" rel="external">Realm</a> project.</p>
+  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external noopener">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external noopener">Realm</a> project.</p>
 </section>
diff --git a/lib/jazzy/themes/apple/templates/header.mustache b/lib/jazzy/themes/apple/templates/header.mustache
@@ -2,17 +2,17 @@
   <div class="content-wrapper">
     <p><a href="{{path_to_root}}index.html">{{docs_title}}</a>{{#doc_coverage}} ({{doc_coverage}}% documented){{/doc_coverage}}</p>
     {{#source_host_url}}
-    <p class="header-right"><a href="{{.}}"><img src="{{path_to_root}}img/{{source_host_image}}"/>View on {{source_host_name}}</a></p>
+    <p class="header-right"><a href="{{.}}"><img src="{{path_to_root}}img/{{source_host_image}}" alt="{{source_host_name}}"/>View on {{source_host_name}}</a></p>
     {{/source_host_url}}
     {{#dash_url}}
-    <p class="header-right"><a href="{{dash_url}}"><img src="{{path_to_root}}img/dash.png"/>Install in Dash</a></p>
+    <p class="header-right"><a href="{{dash_url}}"><img src="{{path_to_root}}img/dash.png" alt="Dash"/>Install in Dash</a></p>
     {{/dash_url}}
     {{^disable_search}}
-    <p class="header-right">
+    <div class="header-right">
       <form role="search" action="{{path_to_root}}search.json">
         <input type="text" placeholder="Search documentation" data-typeahead>
       </form>
-    </p>
+    </div>
     {{/disable_search}}
   </div>
 </header>
diff --git a/lib/jazzy/themes/fullwidth/templates/doc.mustache b/lib/jazzy/themes/fullwidth/templates/doc.mustache
@@ -32,7 +32,7 @@
 
     <p class="breadcrumbs">
       <a class="breadcrumb" href="{{path_to_root}}index.html">{{module_name}} Reference</a>
-      <img class="carat" src="{{path_to_root}}img/carat.png" />
+      <img class="carat" src="{{path_to_root}}img/carat.png" alt=""/>
       {{name}} {{kind}} Reference
     </p>
 
@@ -91,5 +91,4 @@
     </div>
     {{> footer}}
   </body>
-</div>
 </html>
diff --git a/lib/jazzy/themes/fullwidth/templates/footer.mustache b/lib/jazzy/themes/fullwidth/templates/footer.mustache
@@ -1,4 +1,4 @@
 <section class="footer">
   {{{copyright}}}
-  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="noopener" rel="external">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="noopener" rel="external">Realm</a> project.</p>
+  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external noopener">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external noopener">Realm</a> project.</p>
 </section>
diff --git a/lib/jazzy/themes/fullwidth/templates/header.mustache b/lib/jazzy/themes/fullwidth/templates/header.mustache
@@ -7,17 +7,17 @@
   </p>
 
   {{^disable_search}}
-  <p class="header-col--secondary">
+  <div class="header-col--secondary">
     <form role="search" action="{{path_to_root}}search.json">
       <input type="text" placeholder="Search documentation" data-typeahead>
     </form>
-  </p>
+  </div>
   {{/disable_search}}
 
   {{#source_host_url}}
     <p class="header-col header-col--secondary">
       <a class="header-link" href="{{.}}">
-        <img class="header-icon" src="{{path_to_root}}img/{{source_host_image}}"/>
+        <img class="header-icon" src="{{path_to_root}}img/{{source_host_image}}" alt="{{source_host_name}}"/>
         View on {{source_host_name}}
       </a>
     </p>
@@ -26,7 +26,7 @@
   {{#dash_url}}
     <p class="header-col header-col--secondary">
       <a class="header-link" href="{{dash_url}}">
-        <img class="header-icon" src="{{path_to_root}}img/dash.png"/>
+        <img class="header-icon" src="{{path_to_root}}img/dash.png" alt="Dash"/>
         Install in Dash
       </a>
     </p>

diff --git a/lib/jazzy/themes/jony/templates/doc.mustache b/lib/jazzy/themes/jony/templates/doc.mustache
@@ -27,7 +27,7 @@
         <p id="breadcrumbs">
           <span class="no-mobile">
             <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
-            <img id="carat" src="{{path_to_root}}img/carat.png" />
+            <img id="carat" src="{{path_to_root}}img/carat.png" alt=""/>
           </span>
           {{name}} {{kind}} Reference
         </p>
@@ -91,5 +91,4 @@
       </div>
     </div>
   </body>
-</div>
 </html>
diff --git a/lib/jazzy/themes/jony/templates/footer.mustache b/lib/jazzy/themes/jony/templates/footer.mustache
@@ -1,4 +1,4 @@
 <section id="footer">
   {{{copyright}}}
-  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="noopener" rel="external">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="noopener" rel="external">Realm</a> project.</p>
+  <p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external noopener">jazzy ♪♫ v{{jazzy_version}}</a>, a <a class="link" href="https://realm.io" target="_blank" rel="external noopener">Realm</a> project.</p>
 </section>
diff --git a/lib/jazzy/themes/jony/templates/header.mustache b/lib/jazzy/themes/jony/templates/header.mustache
@@ -8,7 +8,7 @@
     {{#source_host_url}}
     <p class="header-right">
       <a href="{{.}}">
-        <img src="{{path_to_root}}img/{{source_host_image}}"/>
+        <img src="{{path_to_root}}img/{{source_host_image}}" alt="{{source_host_name}}"/>
         <span class="no-mobile">View on {{source_host_name}}</span>
       </a>
     </p>
@@ -17,7 +17,7 @@
     {{#dash_url}}
     <p class="header-right">
       <a href="{{dash_url}}">
-        <img src="{{path_to_root}}img/dash.png"/>
+        <img src="{{path_to_root}}img/dash.png" alt="Dash"/>
         <span class="no-mobile">Install in Dash</span>
       </a>
     </p>

diff --git a/spec/integration_specs b/spec/integration_specs