Looking for a way to preserve old links

[zachdaniel]

Hey folks! I'm looking for a way to preserve old links even as documentation changes. As our project evolves, many things change, pages move, modules are renamed, etc. For now, I've added a "this page has moved" extra for one of our extras that has moved that was popular before. However, this sort of thing can also happen for modules, mix tasks, etc.

Two proposals for how this might be resolved:

Explicit moved_pages config

We add a configuration in ex_doc called moved_pages, which would create pages that are not displayed in the sidebar (and probably not in search?) that simply show a message that a given page has been moved, like so:

moved_pages: %{
  "upgrade.html" => "upgrading-to-3.0.html"
}

Since this uses the html route, it can work for modules/mix tasks/anything else.

Add the ability to hide pages in the sidebar

This would only work for extras, since we don't want to leave dead code in a project just for the sake of documentation purposes, but with extras that would be fine. So we could do something like:

extras: [{"Extra", sidebar: false}]

Then if something moves, you can just leave the old page there but hidden in the sidebar.

[zachdaniel]

To solve the specific issue we found, I'm adding a Moved section in our sidebar at the very bottom. Its not ideal, but it works for now.

[josevalim]

We would love a redirects configuration that generates html pages with redirects. +1!

[josevalim]

Probably without the extension, so we automatically generate it.

[zachdaniel]

I will look into it :) I hadn't considered redirects TBH because I was thinking static sites didn't have a good way to do this, but I was wrong and there is metadata you can set to trigger a refresh 👍

[zachdaniel]

Looks like we also already have the setup for redirects for index.html 🥳 this might be easy.

[josevalim]

yes, we can probably even have "index" => main just be an entry that is automatically merged into redirect.

[zachdaniel]

👍 perfect. PR incoming shortly.