Documentation links change from the "server" mode and "build" mode.

Prerequisites

• Put an X between the brackets on this line if you have done all of the following:
  • Checked the Fractal Documentation for information about your issue: https://fractal.build/guide
  • Checked that your issue isn’t already filed: https://github.com/issues?utf8=✓&q=is%3Aissue+user%3Afrctl

Description

Documentation links change from the “server” mode and “build” mode.

When linking related documentation pages together using markdown, the links will either work in “server” mode, or “build” mode, but not both.

Given these pages in the docs/ folder:

01-getting-started.md
02-change-log.md

When running in “server” mode, a link from the first page to the second is written as: [Change Log](./change_log).

When running in “build” mode, a link from the first page to the second is written as: [Change Log](./change_log.html)

Steps to Reproduce

1. Create two markdown pages in the docs/ folder (i.e. “01-getting-started.md” and “02-change-log.md”)
2. Add a markdown link from one page to another, such as [Change Log](./change-log).
3. Start fractal in “server” mode.
4. View the page with the link, and click on the link. It takes you to the second page.
5. Run fractal build
6. Start a static web server which serves the content
7. View the page with the link, and click on the link. It will return an HTTP 404 Not Found error page.

Conversely:

1. Create two markdown pages in the docs/ folder (i.e. “01-getting-started.md” and “02-change-log.md”)
2. Add a markdown link from one page to another, such as [Change Log](./change-log.html).
3. Start fractal in “server” mode.
4. View the page with the link, and click on the link. It returns a fractal Not Found page.
5. Run fractal build
6. Start a static web server which serves the content
7. View the page with the link, and click on the link. It takes you to the second page.

Expected behavior: Links from the “server” mode and “build” mode will be consistent, and don’t require re-writing, depending on the way that fractal is run.

Actual behavior: Links from the “server” mode and “build” mode must be written differently, meaning that either the links don’t work during development, or the links don’t work in the published static site.

Reproduces how often: 100%

Reduced test case: https://gist.github.com/dzwarg/f555265c7ba1ba789d458dbc578382ea

Versions

• What version of Fractal are you running? 1.2.0
• What version of Node.js are you running? 10.16.3

[Chapabu]

My worry with the proposed feature is that it’s a big change. Arguably a BC breaking change. It’s something that could potentially be hidden behind a configuration option, but I’m a bit wary that configuring Fractal is already a bit opaque (in that it differs from the way you configure most other Node apps), and adding more options adds overhead.

I think that in general a better way to link between docs/components would be a good compromise. Maybe we could leverage the current handle system, so something like [Foo](@foo) could be re-written to the correct URL. This would also allow components to be moved without docs breaking. The fact that it’s an invalid link may be a concern, but bearing in mind that these links won’t work anyway until Fractal is either built, or running in server mode - maybe that doesn’t matter?

[mihkeleidast]

Reopened this since this is actually a bug in core.

In order to get the correct URLs, you should use the path helper that’s been provided by most official adapters. For example, with the default handlebars adapter, [Change Log]({{path './change_log'}}) should do the trick.

However, the core utility function that the path helpers in adapters use, returns early for relative paths. This is a bug, since even relative paths should be appended with the proper file extension.