ex_doc Should ex_doc emit a warning when it finds a broken internal link?

Today I was trying to remember some advanced syntax to find jobs using the Oban Web search bar. After checking the Oban Web Overview, I found a broken link; the doc pointed to search.md instead of searching.md (an internal doc or guide), I reported the issue, and now it's fixed. But @sorentwo made a good suggestion, or I think we should consider it, which is that ex_doc should verify links.

So, I wonder if ex_doc should support verifying links for at least internal docs and warn the users once it has processed all the files. Please let me know what do you think.

Mar 05 '22 04:03 milmazz

I thought we did that already. I will investigate.

Mar 05 '22 05:03 wojtekmach

It is hard to warn for html links but I think we can warn for .md ones indeed!

Mar 05 '22 08:03 josevalim

I tried reproducing this using the main branch but failed to, is there something I'm missing?

# lib/test_mix_app.ex
defmodule TestMixApp do
  @moduledoc """
  Documentation for `TestMixApp`.

  Hey Link! [Take this link!](README.md)

  Hey Link! [Don't Take this broken link!](READMEeee.md)
  """

  @doc """
  Hello world.

  ## Examples

      iex> TestMixApp.hello()
      :world

  """
  def hello do
    :world
  end
end

# mix.exs
defmodule TestMixApp.MixProject do
  use Mix.Project

  def project do
    [
      app: :test_mix_app,
      version: "0.1.0",
      elixir: "~> 1.14",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
 
      docs: [
        extras: [
          "README.md": [title: "README !!!"]
        ]
      ]
    ]
  end

  # Run "mix help compile.app" to learn about applications.
  def application do
    [
      extra_applications: [:logger]
    ]
  end

  # Run "mix help deps" to learn about dependencies.
  defp deps do
    [
      # {:ex_doc, "~> 0.27", only: :dev, runtime: false},
      {:ex_doc, path: "../ex_doc"},
    ]
  end
end

When running mix docs I get the following output:

$ mix docs
Generating docs...
warning: documentation references file "READMEeee.md" but it does not exist
  lib/test_mix_app.ex:2: TestMixApp

View "html" docs at "doc/index.html"
warning: documentation references file "READMEeee.md" but it does not exist
  lib/test_mix_app.ex:2: TestMixApp

View "epub" docs at "doc/test_mix_app.epub"

Edit: I was missing the backticks inside the links

May 21 '23 21:05 viniciusmuller

Perfect, so we have addressed this :) thanks for Checking!

May 21 '23 22:05 josevalim

@josevalim But if quotes are added on the link, (`README.md`) then it fails silently, I think either only one of these should be valid syntax for linking pages or it should also warn when using backticks and linking to an invalid filename.

May 21 '23 22:05 viniciusmuller

Yeah, the quotes should not be supported. That’s only for functions and module names. unless it thinks it is the md function in the README module?

May 22 '23 05:05 josevalim

Is there any good way to handle this? I guess one should check if a function md without arity was passed and emit a warning, but this might lead to false positives if someone refences a legit function called md

May 22 '23 10:05 viniciusmuller

Do you mean if the user wrote (`README`) or [whatever](`README.md`) or both?

May 22 '23 10:05 wojtekmach