hexdocs のトップページを README.md にする

最近作っているライブラリを Hex.pm で公開するときに少しハマったので書き残しておく。

ドキュメントのトップページを README.md にする

ドキュメントをほとんど書いていないので、とりあえずトップページを README にするために、ExDoc の README を参考に以下のようにした。

def project do
  [
    ...
    docs: [
      main: "README",
      extras: ["README.md"]
    ]
  ]
end

しかし、PAGE NOT FOUND

ローカルで問題なく動いていることを確認して、 mix hex.publish で公開。しかし、公開自体はうまくいったが、Page Not Found になる...😰

Works on my machine なのに何故...

[解決] ファイル名は小文字

Hex.pm の FAQ に書いてあった。

also verify that there are no differences in letter casing since Hexdocs is case-sensitive but your machine may be case-insensitive.

Mac のファイルシステムは大文字・小文字を無視するが、Hexdoc で使われてるファイルシステムでは区別するので、以下のように変更する必要がある。

def project do
  [
    ...
    docs: [
      main: "readme",
      extras: ["README.md"]
    ]
  ]
end

ブラウザのキャッシュも更新が必要

公開されたドキュメントはブラウザにキャッシュされているので、キャッシュもクリアする必要がある。