Documentation for docs_config.js and versionNodes

[garazdawi]

Hello!

I'm trying to implement the version dropdown on erlang.org/doc and can't find any documentation for how the docs_config.js file should look and work? Also the release note where it was added mentions that its location can be configured, but that does not seem to be documented anywhere either?

I've dug through the code and have a basic understanding on how it works, but I think it would be good to add to the documentation in order to know which behaviour we can rely on.

[wojtekmach]

yeah, the var versionNodes = format is straightforward but yes, I agree it should be documented. Perhaps the location was configured at some point but right now I see it needs to a relative docs_config.js to html files. In any case, if you have any questions about this, let us know!

[garazdawi]

One thing that popped up when digging was that it seems like the version needs to be "v" + actual version. So for 28.0, the version needs to be v28.0.

[wojtekmach]

For ExDoc itself, it seems it can be without v,

~/src/ex_doc[main]$ git diff
diff --git a/mix.exs b/mix.exs
index 306d848f..e2731be2 100644
--- a/mix.exs
+++ b/mix.exs
@@ -120,7 +120,7 @@ defmodule ExDoc.Mixfile do
     list_contents =
       Enum.map_intersperse(versions, ", ", fn version ->
         string = Version.to_string(version)
-        ~s[{"version":"v#{string}", "url":"https://hexdocs.pm/ex_doc/#{string}"}]
+        ~s[{"version":"#{string}", "url":"https://hexdocs.pm/ex_doc/#{string}"}]
       end)

     File.write!("doc/docs_config.js", """

and then:

~/src/ex_doc[main]$ mix docs

but yeah, no idea if other parts or other tools make assumption about this.

[garazdawi]

Not sure if it is related, but the <meta name="project"> seems to prepend v to the version: https://github.com/elixir-lang/ex_doc/blob/main/lib/ex_doc/formatter/html/templates/head_template.eex#L8.

[josevalim]

Please send a PR where we stop prepending the "v" and I will see if and how it impacts Elixir. :) I can look into it, but it will probably be in a week or two.

[garazdawi]

I'm afraid I don't have time either, I'm going on parental leave tomorrow and will be back again next year. Just thought I'd do this one last thing before I'm off.. :)