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

[dzwarg]

Prerequisites

• [X] 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=%E2%9C%93&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

[LeBenLeBen]

I guess the build mecanism should be refactored to output components as index.html files into sub-folders to avoid having to add the .html extension…

In the meantime, I suggest you create a custom method for the templating language of your choice to dynamically build one or the other based on the Node environment. Here's an example as a Nunjucks filter:

link(handle) {
  const name = handle.replace('@', '');
  let prefix = '';
  let ext = '';

  if (process.env.NODE_ENV === 'production') {
    prefix = '../..';
    ext = '.html';
  }

  return `<a href="${prefix}/components/detail/${name}${ext}">${handle}</a>`;
},

You can then add a link to a component with {{ '@my-component-handle' | link }}, for example in you components notes or in docs.

See Nunjucks adapter docs on how to configure a custom filter.

Also note that this requires your Node environment to be properly set when running Fractal commands. For example:

$ NODE_ENV=production fractal build

[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?

[ccardinaux]

Was just trying to find a solution to this, being able to leverage the handle system would be very helpful!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[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.