Allow listing outside URLs in extras #2103
Conversation
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 elixir-lang#2084
sorentwo
force-pushed
the
allow-extra-urls
branch
from
68d3c53 to
639afcc
Compare
| if custom_search_data = map[:search_data] do | ||
| extra_search_data(map, custom_search_data) | ||
| else |
There was a problem hiding this comment.
Added a clause for this rather than a conditional in the function body.
|
For the |
|
Suggestions applied, changes made , and residual TODO items addressed. This is all set! |
| @@ -59,6 +31,34 @@ defmodule ExDoc.Formatter.HTML.SearchData do | |||
| end) | |||
| end | |||
|
|
|||
| defp extra(%{url: url} = map) do | |||
| [encode("#{map.id}", map.title, :extras, url)] | |||
There was a problem hiding this comment.
Sorry, I should have caught it the first time around, but I am thinking this likely should not show up on search? I.e. we should skip URLs here too.
There was a problem hiding this comment.
And let's add a test for whatever decision we pick here. :)
| @@ -378,6 +379,7 @@ defmodule Mix.Tasks.Docs do | |||
| title but keep the source file unchanged. | |||
| * `: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. | |||
| * `:url` - An external url to link to from the sidebar. | |||
There was a problem hiding this comment.
I am thinking we could break it apart like this:
## Customizing Extras
There are two sources for extras, filenames and urls.
For filenames, the allowed configuration is:
* ...
For urls:
* title
* url
| @@ -112,6 +112,24 @@ defmodule ExDoc.Formatter.HTMLTest do | |||
| assert LazyHTML.text(bar_content["h1"]) == "README bar" | |||
| end | |||
|
|
|||
| test "extras defined as external urls", %{tmp_dir: tmp_dir} = context do | |||
| config = | |||
There was a problem hiding this comment.
I think we should add a test that shows grouping work. Imagine you want all URLs in a section in the sidebar called Important Links. The Template.sidebar_extras kinda implies URLs work with groups but we need to be sure it works "end to end".
There was a problem hiding this comment.
It seems groups expect the filename but there is none here, so we probably have to pass the filename or the url (and update its docs accordingly).
| @@ -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` | |||
There was a problem hiding this comment.
Should we add an icon, such as this one, for URLs?
If so, you can upload this bundle to remixicon.com, add external link, and get the new font back: https://github.com/elixir-lang/ex_doc/blob/main/assets/fonts/RemixIconCollection.remixicon
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:
This is currently light on some validations. I'll expand the tests and URI validation if the approach is improved.
Validate theurlvalue is an actual URIExpand formatter testsurloptionsCloses #2084