Add source link and Livebook badge to extras (#1408)

Author: jonatanklosko

assets/js/content.js

@@ -1,14 +1,16 @@
-import { qs } from './helpers'
+import { qs, qsAll } from './helpers'
 
 const CONTENT_SELECTOR = '.content'
 const CONTENT_INNER_SELECTOR = '.content-inner'
+const LIVEBOOK_BADGE_ANCHOR_SELECTOR = '.livebook-badge'
 
 /**
  * Runs some general modifiers on the documentation content.
  */
 export function initialize () {
   fixLinks()
   fixSpacebar()
+  setLivebookBadgeUrl()
 }
 
 /**
@@ -34,3 +36,14 @@ function fixSpacebar () {
   qs(CONTENT_INNER_SELECTOR).setAttribute('tabindex', -1)
   qs(CONTENT_INNER_SELECTOR).focus()
 }
+
+function setLivebookBadgeUrl () {
+  const path = window.location.pathname
+  const notebookPath = path.replace(/\.html$/, '.livemd')
+  const notebookUrl = new URL(notebookPath, window.location.href).toString()
+  const targetUrl = `https://livebook.dev/run?url=${encodeURIComponent(notebookUrl)}`
+
+  for (const anchor of qsAll(LIVEBOOK_BADGE_ANCHOR_SELECTOR)) {
+    anchor.href = targetUrl
+  }
+}

assets/less/content/general.less

@@ -64,6 +64,10 @@ a.view-source {
   }
 }
 
+a.livebook-badge {
+  display: flex;
+}
+
 .note {
   color: #727272;
   margin-right: 5px;

lib/ex_doc/doc_ast.ex

@@ -24,7 +24,7 @@ defmodule ExDoc.DocAST do
   end
 
   # https://www.w3.org/TR/2011/WD-html-markup-20110113/syntax.html#void-element
-  @void_elements ~W(area base br col command embed hr img input keygen link 
+  @void_elements ~W(area base br col command embed hr img input keygen link
     meta param source track wbr)a
 
   @doc """
@@ -94,6 +94,38 @@ defmodule ExDoc.DocAST do
     {tag, attrs, parse_erl_ast(content), %{}}
   end
 
+  @doc """
+  Extracts leading title element from the given AST.
+
+  If found, the title element is stripped from the resulting AST.
+  """
+  def extract_title(ast)
+
+  def extract_title([{:h1, _attrs, inner, _meta} | ast]) do
+    {:ok, inner, ast}
+  end
+
+  def extract_title(_ast) do
+    :error
+  end
+
+  @doc """
+  Returns text content from the given AST.
+  """
+  def text_from_ast(ast) do
+    ast
+    |> do_text_from_ast()
+    |> IO.iodata_to_binary()
+    |> String.trim()
+  end
+
+  def do_text_from_ast(ast) when is_list(ast) do
+    Enum.map(ast, &do_text_from_ast/1)
+  end
+
+  def do_text_from_ast(ast) when is_binary(ast), do: ast
+  def do_text_from_ast({_tag, _attr, ast, _meta}), do: text_from_ast(ast)
+
   @doc """
   Highlights a DocAST converted to string.
   """

lib/ex_doc/formatter/epub.ex

@@ -57,9 +57,9 @@ defmodule ExDoc.Formatter.EPUB do
 
   defp generate_extras(config) do
     for {_title, extras} <- config.extras do
-      Enum.each(extras, fn %{id: id, title: title, content: content} ->
+      Enum.each(extras, fn %{id: id, title: title, title_content: title_content, content: content} ->
         output = "#{config.output}/OEBPS/#{id}.xhtml"
-        html = Templates.extra_template(config, title, content)
+        html = Templates.extra_template(config, title, title_content, content)
 
         if File.regular?(output) do
           IO.puts(:stderr, "warning: file #{Path.relative_to_cwd(output)} already exists")

lib/ex_doc/formatter/epub/templates.ex

@@ -76,7 +76,7 @@ defmodule ExDoc.Formatter.EPUB.Templates do
     :def,
     :extra_template,
     Path.expand("templates/extra_template.eex", __DIR__),
-    [:config, :title, :content],
+    [:config, :title, :title_content, :content],
     trim: true
   )
 

lib/ex_doc/formatter/epub/templates/extra_template.eex

@@ -1,4 +1,7 @@
 <%= head_template(config, %{title: title}) %>
+    <h1 id="content">
+      <%= title_content %>
+    </h1>
     <%= content %>
     <%# Extra content specified by the user (e.g. custom Javascript) %>
     <%= config.before_closing_body_tag.(:epub) %>

lib/ex_doc/formatter/html.ex

@@ -230,7 +230,7 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp copy_extras(config, extras) do
-    for %{source_path: source_path, id: id} <- extras,
+    for %{source_path: source_path, id: id} when source_path != nil <- extras,
         ext = extension_name(source_path),
         ext == ".livemd" do
       output = "#{config.output}/#{id}#{ext}"
@@ -293,7 +293,16 @@ defmodule ExDoc.Formatter.HTML do
 
   defp build_api_reference(nodes_map, config) do
     api_reference = Templates.api_reference_template(config, nodes_map)
-    %{id: "api-reference", title: "API Reference", group: "", content: api_reference}
+
+    %{
+      id: "api-reference",
+      title: "API Reference",
+      group: "",
+      title_content: "API Reference",
+      content: api_reference,
+      source_path: nil,
+      source_url: nil
+    }
   end
 
   @doc """
@@ -346,14 +355,40 @@ defmodule ExDoc.Formatter.HTML do
                 "file extension not recognized, allowed extension is either .md, .txt or no extension"
       end
 
+    {title_ast, ast} =
+      case ExDoc.DocAST.extract_title(ast) do
+        {:ok, title_ast, ast} -> {title_ast, ast}
+        :error -> {nil, ast}
+      end
+
+    title_text = title_ast && ExDoc.DocAST.text_from_ast(title_ast)
+    title_html = title_ast && ExDoc.DocAST.to_string(title_ast)
+
     # TODO: don't hardcode Elixir for extras?
     language = ExDoc.Language.Elixir
-    html_content = autolink_and_render(ast, language, autolink_opts, opts)
+    content_html = autolink_and_render(ast, language, autolink_opts, opts)
 
     group = GroupMatcher.match_extra(groups, input)
-    title = title || extract_title(html_content) || filename_to_title(input)
+    title = title || title_text || filename_to_title(input)
+
+    source_path = Path.relative_to(input, ".")
+
+    source_url =
+      if url = config.source_url_pattern do
+        url
+        |> String.replace("%{path}", source_path)
+        |> String.replace("%{line}", "1")
+      end
 
-    %{id: id, title: title, group: group, content: html_content, source_path: input}
+    %{
+      id: id,
+      title: title,
+      group: group,
+      title_content: title_html,
+      content: content_html,
+      source_path: source_path,
+      source_url: source_url
+    }
   end
 
   defp extension_name(input) do
@@ -362,20 +397,6 @@ defmodule ExDoc.Formatter.HTML do
     |> String.downcase()
   end
 
-  @tag_regex ~r/<[^>]*>/m
-  defp strip_html(header) do
-    Regex.replace(@tag_regex, header, "")
-  end
-
-  @h1_regex ~r/<h1.*?>(.+?)<\/h1>/m
-  defp extract_title(content) do
-    title = Regex.run(@h1_regex, content, capture: :all_but_first)
-
-    if title do
-      title |> List.first() |> strip_html() |> String.trim()
-    end
-  end
-
   @doc """
   Convert the input file name into a title
   """

lib/ex_doc/formatter/html/templates/extra_template.eex

@@ -1,6 +1,22 @@
 <%= head_template(config, %{title: node.title, type: :extra}) %>
 <%= sidebar_template(config, nodes_map) %>
 
+<h1 id="content">
+  <%= node.title_content %>
+  <%= if node.source_url do %>
+    <a href="<%= node.source_url %>" title="View Source" class="view-source" rel="help">
+      <span class="icon-code" aria-hidden="true"></span>
+      <span class="sr-only">View Source</span>
+    </a>
+  <% end %>
+</h1>
+
+<%= if node.source_path && String.ends_with?(node.source_path, ".livemd") do %>
+  <a href="#" class="livebook-badge">
+    <img src="https://livebook.dev/badge/v1/blue.svg" alt="Run in Livebook" width="150" />
+  </a>
+<% end %>
+
 <%= link_headings(node.content) %>
 <%= bottom_actions_template(refs) %>
 <%= footer_template(config, node) %>

test/ex_doc/formatter/html_test.exs

@@ -344,6 +344,9 @@ defmodule ExDoc.Formatter.HTMLTest do
       assert content =~
                ~r{<a href="https://hexdocs.pm/mix/Mix.Tasks.Compile.Elixir.html"><code(\sclass="inline")?>mix compile.elixir</code></a>}
 
+      refute content =~
+               ~R{<img src="https://livebook.dev/badge/v1/blue.svg" alt="Run in Livebook" width="150" />}
+
       assert content =~ "<p><strong>raw content</strong></p>"
 
       content = File.read!("#{output_dir()}/plaintextfiles.html")
@@ -368,6 +371,9 @@ defmodule ExDoc.Formatter.HTMLTest do
 
       assert content =~
                ~R{<p>Read <code class="inline">.livemd</code> files generated by <a href="https://github.com/livebook-dev/livebook">livebook</a>.}
+
+      assert content =~
+               ~R{<img src="https://livebook.dev/badge/v1/blue.svg" alt="Run in Livebook" width="150" />}
     end
 
     test "without any other content" do