Allow listing outside URLs in extras (#2103)

sorentwo · web-flow · commit 15f3a5938986 · 2025-04-26T20:40:55.000+02:00
This makes it possible to delcare URLs as extras and have them listed as links in the sidebar. For example, to set a "Wikipedia" url: ```elixir extras: [ "Wikipedia": [url: "https://wikipedia.com"] ] ``` Closes #2084
diff --git a/assets/css/icons.css b/assets/css/icons.css
@@ -24,6 +24,7 @@
   --icon-add: "\ea13";
   --icon-subtract: "\f1af";
   --icon-error-warning: "\eca1";
+  --icon-external-link-line: "\ecaf";
   --icon-information: "\ee59";
   --icon-alert: "\ea21";
   --icon-double-quotes-l: "\ec51";
@@ -44,6 +45,7 @@
 .ri-arrow-up-s-line:before { content: var(--icon-arrow-up-s); }
 .ri-arrow-down-s-line:before { content: var(--icon-arrow-down-s); }
 .ri-arrow-right-s-line:before { content: var(--icon-arrow-right-s); }
+.ri-external-link-line:before { content: var(--icon-external-link-line); }
 .ri-search-2-line:before { content: var(--icon-search-2-line); }
 .ri-menu-line:before { content: var(--icon-menu-line); }
 .ri-close-line:before { content: var(--icon-close-line); }
diff --git a/assets/css/sidebar.css b/assets/css/sidebar.css
@@ -37,6 +37,10 @@
   color: var(--sidebarHover);
 }
 
+.sidebar .external-link {
+  margin: 0 2.5px 0 0;
+}
+
 .sidebar .sidebar-header {
   background-color: var(--sidebarHeader);
   width: 100%;
diff --git a/assets/fonts/RemixIconCollection.remixicon b/assets/fonts/RemixIconCollection.remixicon
@@ -1 +1 @@
-settings-3-line,add-line,subtract-line,arrow-up-s-line,arrow-down-s-line,arrow-right-s-line,search-2-line,menu-line,close-line,link-m,code-s-slash-line,error-warning-line,information-line,alert-line,double-quotes-l,printer-line
+add-line,alert-line,arrow-down-s-line,arrow-right-s-line,arrow-up-s-line,close-line,code-s-slash-line,double-quotes-l,error-warning-line,external-link-line,information-line,link-m,menu-line,printer-line,search-2-line,settings-3-line,subtract-line
diff --git a/assets/fonts/remixicon.woff2 b/assets/fonts/remixicon.woff2
diff --git a/assets/js/sidebar/sidebar-list.js b/assets/js/sidebar/sidebar-list.js
@@ -59,6 +59,7 @@ export function initialize () {
       const items = []
       const hasHeaders = Array.isArray(node.headers)
       const translate = hasHeaders ? undefined : 'no'
+      const href = node?.url || `${node.id}.html`
 
       // Group header.
       if (node.group !== group) {
@@ -78,7 +79,10 @@ export function initialize () {
       }
 
       items.push(el('li', {}, [
-        el('a', {href: `${node.id}.html`, translate}, [node.nested_title || node.title]),
+        el('a', {href, translate}, [
+          node.nested_title || node.title,
+          node.url ? el('i', {class: 'external-link ri-external-link-line'}) : null
+        ].filter(Boolean)),
         ...childList(`node-${node.id}-headers`,
           hasHeaders
             ? renderHeaders(node)
diff --git a/formatters/html/dist/html-AG646WP7.js b/formatters/html/dist/html-AG646WP7.js
diff --git a/lib/ex_doc/formatter/epub.ex b/lib/ex_doc/formatter/epub.ex
@@ -61,17 +61,19 @@ defmodule ExDoc.Formatter.EPUB do
   end
 
   defp generate_extras(config) do
-    for {_title, extras} <- config.extras do
-      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, title_content, content)
+    for {_title, extras} <- config.extras,
+        extra_config <- extras,
+        not is_map_key(extra_config, :url) do
+      %{id: id, title: title, title_content: title_content, content: content} = extra_config
 
-        if File.regular?(output) do
-          Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
-        end
+      output = "#{config.output}/OEBPS/#{id}.xhtml"
+      html = Templates.extra_template(config, title, title_content, content)
 
-        File.write!(output, html)
-      end)
+      if File.regular?(output) do
+        Utils.warn("file #{Path.relative_to_cwd(output)} already exists", [])
+      end
+
+      File.write!(output, html)
     end
   end
 
diff --git a/lib/ex_doc/formatter/html.ex b/lib/ex_doc/formatter/html.ex
@@ -209,6 +209,7 @@ defmodule ExDoc.Formatter.HTML do
   defp generate_extras(extras, config) do
     generated_extras =
       extras
+      |> Enum.reject(&is_map_key(&1, :url))
       |> with_prev_next()
       |> Enum.map(fn {node, prev, next} ->
         filename = "#{node.id}.html"
@@ -349,6 +350,7 @@ defmodule ExDoc.Formatter.HTML do
 
     extras =
       config.extras
+      |> Enum.map(&normalize_extras/1)
       |> Task.async_stream(
         &build_extra(&1, groups, language, autolink_opts, source_url_pattern),
         timeout: :infinity
@@ -384,10 +386,21 @@ defmodule ExDoc.Formatter.HTML do
     end)
   end
 
+  defp normalize_extras(base) when is_binary(base), do: {base, %{}}
+  defp normalize_extras({base, opts}), do: {base, Map.new(opts)}
+
   defp disambiguate_id(extra, discriminator) do
     Map.put(extra, :id, "#{extra.id}-#{discriminator}")
   end
 
+  defp build_extra({input, %{url: _} = input_options}, groups, _lang, _auto, _url_pattern) do
+    input = to_string(input)
+    title = input_options[:title] || input
+    group = GroupMatcher.match_extra(groups, input_options[:url])
+
+    %{group: group, id: Utils.text_to_id(title), title: title, url: input_options[:url]}
+  end
+
   defp build_extra({input, input_options}, groups, language, autolink_opts, source_url_pattern) do
     input = to_string(input)
     id = input_options[:filename] || input |> filename_to_title() |> Utils.text_to_id()
@@ -447,10 +460,6 @@ defmodule ExDoc.Formatter.HTML do
     }
   end
 
-  defp build_extra(input, groups, language, autolink_opts, source_url_pattern) do
-    build_extra({input, []}, groups, language, autolink_opts, source_url_pattern)
-  end
-
   defp normalize_search_data!(nil), do: nil
 
   defp normalize_search_data!(search_data) when is_list(search_data) do
@@ -595,14 +604,23 @@ defmodule ExDoc.Formatter.HTML do
   end
 
   defp extra_paths(config) do
-    Map.new(config.extras, fn
-      path when is_binary(path) ->
+    Enum.reduce(config.extras, %{}, fn
+      path, acc when is_binary(path) ->
         base = Path.basename(path)
-        {base, Utils.text_to_id(Path.rootname(base))}
 
-      {path, opts} ->
-        base = path |> to_string() |> Path.basename()
-        {base, opts[:filename] || Utils.text_to_id(Path.rootname(base))}
+        Map.put(acc, base, Utils.text_to_id(Path.rootname(base)))
+
+      {path, opts}, acc ->
+        if Keyword.has_key?(opts, :url) do
+          acc
+        else
+          base = path |> to_string() |> Path.basename()
+
+          name =
+            Keyword.get_lazy(opts, :filename, fn -> Utils.text_to_id(Path.rootname(base)) end)
+
+          Map.put(acc, base, name)
+        end
     end)
   end
 end
diff --git a/lib/ex_doc/formatter/html/search_data.ex b/lib/ex_doc/formatter/html/search_data.ex
@@ -18,36 +18,10 @@ defmodule ExDoc.Formatter.HTML.SearchData do
     ["searchData=" | ExDoc.Utils.to_json(data)]
   end
 
-  defp extra(map) do
-    if custom_search_data = map[:search_data] do
-      extra_search_data(map, custom_search_data)
-    else
-      {intro, sections} = extract_sections_from_markdown(map.source)
-
-      intro_json_item =
-        encode(
-          "#{map.id}.html",
-          map.title,
-          :extras,
-          intro
-        )
-
-      section_json_items =
-        for {header, body} <- sections do
-          encode(
-            "#{map.id}.html##{Utils.text_to_id(header)}",
-            header <> " - #{map.title}",
-            :extras,
-            body
-          )
-        end
-
-      [intro_json_item | section_json_items]
-    end
-  end
+  defp extra(%{url: _}), do: []
 
-  defp extra_search_data(map, custom_search_data) do
-    Enum.map(custom_search_data, fn item ->
+  defp extra(%{search_data: search_data} = map) when is_list(search_data) do
+    Enum.map(search_data, fn item ->
       link =
         if item.anchor === "" do
           "#{map.id}.html"
@@ -59,6 +33,30 @@ defmodule ExDoc.Formatter.HTML.SearchData do
     end)
   end
 
+  defp extra(map) do
+    {intro, sections} = extract_sections_from_markdown(map.source)
+
+    intro_json_item =
+      encode(
+        "#{map.id}.html",
+        map.title,
+        :extras,
+        intro
+      )
+
+    section_json_items =
+      for {header, body} <- sections do
+        encode(
+          "#{map.id}.html##{Utils.text_to_id(header)}",
+          header <> " - #{map.title}",
+          :extras,
+          body
+        )
+      end
+
+    [intro_json_item | section_json_items]
+  end
+
   defp module(%ExDoc.ModuleNode{} = node) do
     {intro, sections} = extract_sections(node.doc_format, node)
 
diff --git a/lib/ex_doc/formatter/html/templates.ex b/lib/ex_doc/formatter/html/templates.ex
@@ -58,15 +58,9 @@ defmodule ExDoc.Formatter.HTML.Templates do
 
   defp sidebar_extras(extras) do
     for extra <- extras do
-      %{id: id, title: title, group: group, content: content} = extra
+      %{id: id, title: title, group: group} = extra
 
-      item =
-        %{
-          id: to_string(id),
-          title: to_string(title),
-          group: to_string(group),
-          headers: extract_headers(content)
-        }
+      item = %{id: to_string(id), title: to_string(title), group: to_string(group)}
 
       case extra do
         %{search_data: search_data} when is_list(search_data) ->
@@ -79,10 +73,15 @@ defmodule ExDoc.Formatter.HTML.Templates do
               }
             end)
 
-          Map.put(item, :searchData, search_data)
+          item
+          |> Map.put(:headers, extract_headers(extra.content))
+          |> Map.put(:searchData, search_data)
+
+        %{url: url} when is_binary(url) ->
+          Map.put(item, :url, url)
 
         _ ->
-          item
+          Map.put(item, :headers, extract_headers(extra.content))
       end
     end
   end
diff --git a/lib/ex_doc/group_matcher.ex b/lib/ex_doc/group_matcher.ex
@@ -46,13 +46,13 @@ defmodule ExDoc.GroupMatcher do
   end
 
   @doc """
-  Finds a matching group for the given extra filename
+  Finds a matching group for the given filename or url.
   """
-  def match_extra(group_patterns, filename) do
+  def match_extra(group_patterns, path) do
     match_group_patterns(group_patterns, fn pattern ->
       case pattern do
-        %Regex{} = regex -> Regex.match?(regex, filename)
-        string when is_binary(string) -> filename == string
+        %Regex{} = regex -> Regex.match?(regex, path)
+        string when is_binary(string) -> path == string
       end
     end)
   end
diff --git a/lib/mix/tasks/docs.ex b/lib/mix/tasks/docs.ex
@@ -111,11 +111,12 @@ defmodule Mix.Tasks.Docs do
       Markdown and plain text pages; default: "PAGES". Example: "GUIDES"
 
     * `:extras` - List of paths to additional Markdown (`.md` extension), Live Markdown
-      (`.livemd` extension), Cheatsheets (`.cheatmd` extension) and plain text pages to
-      add to the documentation. You can also specify keyword pairs to customize the
-      generated filename, title and source file, and search content of each extra page; default: `[]`. Example:
-      `["README.md", "LICENSE", "CONTRIBUTING.md": [filename: "contributing", title: "Contributing", source: "CONTRIBUTING.mdx"]]`
-      See the Customizing Extras section for more.
+      (`.livemd` extension), Cheatsheets (`.cheatmd` extension), external urls (`:url` option),
+      and plain text pages to add to the documentation. You can also specify keyword pairs to
+      customize the generated filename, title and source file, and search content of each extra page;
+      default: `[]`. Example: `["README.md", "LICENSE", "CONTRIBUTING.md": [filename: "contributing",
+      title: "Contributing", source: "CONTRIBUTING.mdx"]]` See the Customizing Extras section for
+      more.
 
     * `:favicon` - Path to a favicon image file for the project. Must be PNG, JPEG or SVG. When
       specified, the image file will be placed in the output "assets" directory, named
@@ -276,6 +277,13 @@ defmodule Mix.Tasks.Docs do
         "Advanced": ~r"/advanced/"
       ]
 
+  External extras from a URL can also be grouped:
+
+      groups_for_extras: [
+        "Elixir": ~r"https://elixir-lang.org/",
+        "Erlang": ~r"https://www.erlang.org/"
+      ]
+
   Similar can be done for modules:
 
       groups_for_modules: [
@@ -402,6 +410,10 @@ defmodule Mix.Tasks.Docs do
 
   ## Customizing Extras
 
+  There are two sources for extras, filenames and urls.
+
+  For filenames, the allowed configuration is:
+
     * `:title` - The title of the extra page. If not provided, the title will be inferred from the filename.
     * `:filename` - The name of the generated file. If not provided, the filename will be inferred from
        the source file.
@@ -410,6 +422,11 @@ defmodule Mix.Tasks.Docs do
     * `:search_data` - A list of terms to be indexed for autocomplete and search. If not provided, the content
        of the extra page will be indexed for search. See the section below for more.
 
+  For urls:
+
+    * `:title` - The title of the extra page. If not provided, the title will be inferred from the extra name.
+    * `:url` - The external url to link to from the sidebar.
+
   ### Customizing Search Data
 
   It is possible to fully customize the way a given extra is indexed, both in autocomplete and in search.
diff --git a/test/ex_doc/formatter/epub_test.exs b/test/ex_doc/formatter/epub_test.exs
@@ -146,6 +146,17 @@ defmodule ExDoc.Formatter.EPUBTest do
     assert content =~ ~r{<li><a href="readme.xhtml">README</a></li>}
   end
 
+  test "ignores any external url extras", %{tmp_dir: tmp_dir} = context do
+    config =
+      context
+      |> doc_config()
+      |> Keyword.put(:extras, elixir: [url: "https://elixir-lang.org"])
+
+    generate_docs_and_unzip(context, config)
+
+    refute File.exists?(tmp_dir <> "/epub/OEBPS/elixir.xhtml")
+  end
+
   test "uses samp as highlight tag for markdown", %{tmp_dir: tmp_dir} = context do
     generate_docs_and_unzip(context, doc_config(context))
 
diff --git a/test/ex_doc/formatter/html/search_data_test.exs b/test/ex_doc/formatter/html/search_data_test.exs
@@ -204,7 +204,12 @@ defmodule ExDoc.Formatter.HTML.SearchDataTest do
     Section _1_ content.
     """)
 
-    config = %ExDoc.Config{output: "#{c.tmp_dir}/doc", extras: [readme_path]}
+    extras = [
+      readme_path,
+      "Elixir": [url: "https://elixir-lang.org"]
+    ]
+
+    config = %ExDoc.Config{output: "#{c.tmp_dir}/doc", extras: extras}
     [item1, item2] = search_data([], config)["items"]
 
     assert item1["ref"] == "readme.html"
diff --git a/test/ex_doc/formatter/html_test.exs b/test/ex_doc/formatter/html_test.exs
diff --git a/test/ex_doc/group_matcher_test.exs b/test/ex_doc/group_matcher_test.exs

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-settings-3-line,add-line,subtract-line,arrow-up-s-line,arrow-down-s-line,arrow-right-s-line,search-2-line,menu-line,close-line,link-m,code-s-slash-line,error-warning-line,information-line,alert-line,double-quotes-l,printer-line`
	`1`	`+add-line,alert-line,arrow-down-s-line,arrow-right-s-line,arrow-up-s-line,close-line,code-s-slash-line,double-quotes-l,error-warning-line,external-link-line,information-line,link-m,menu-line,printer-line,search-2-line,settings-3-line,subtract-line`