(Docs): Routes for internal relative links are root-relative and therefore broken for in-app docs

[tonyketcham]

1) The issue and what you expected to happen

Clicking on links of internal references while using the in-app documentation gives the user a route error instead of taking them to the intended page.

2) Exact steps to reproduce this issue

Clicking a relative link in the in-app documentation as an admin user:

Results in this error:
https://<example-domain>/concepts/items/

{
  "errors": [
    {
      "message": "Route /concepts/items/ doesn't exist.",
      "extensions": {
        "code": "ROUTE_NOT_FOUND"
      }
    }
  ]
}

For the in-app documentation, the above route should resolve to:
https://<example-domain>/admin/docs/concepts/items/

3) Your environment:

Directus v9.0.0-rc.69
Deployment: npx
Version 1.18.78 Chromium: 87.0.4280.141 (Official Build)

[tonyketcham]

A potential solution could be adding a custom permalink rendering function in the markdown.anchor config of the docs' VuePress instance. That function could reference a new environment variable DOCS_PATH which, if defined, prefixes internal relative links with the declared path.

Then the in-app environment would have:
DOCS_PATH=/admin/docs

And docs.directus.io could fall back to the default of prefixing nothing.

[rijkvanzanten]

Currently, the docs module should handle clicks and use vue-router to navigate when clicking on an anchor:

directus/app/src/modules/docs/components/markdown.vue

Lines 112 to 130 in de39b92

	function onClick(event: MouseEvent) {
	if (
	event.target &&
	(event.target as HTMLElement).tagName.toLowerCase() === 'a' &&
	(event.target as HTMLAnchorElement).href
	) {
	const link = (event.target as HTMLAnchorElement).getAttribute('href')!;
	if (link.startsWith('http') || link.startsWith('#')) return;
	event.preventDefault();
	const parts = link.split('#');
	parts[0] = parts[0].endsWith('/') ? parts[0].slice(0, -1) : parts[0];
	router.push({
	path: `/docs${parts[0]}`,
	hash: parts[1],
	});
	}
	}

Not sure why that doesn't seem to work on your end 🤔

[rijkvanzanten]

markdown.anchor is markdown-it-anchor is only for header links, so won't really help here

[rijkvanzanten]

Thank you for taking the time to submit this! Unfortunately, our team was not been able to reproduce it based on the information provided. Therefore, we will close this ticket for now, but will happily re-open it if new details are provided that allow us to reliably replicate the problem.

As a reminder:

• Provide as much detail as possible in the issue description
• Video screen captures and clear steps are very helpful
• A full SQL dump is the fastest way for us to test/resolve (can be sent privately)
• Make sure you are on the latest version of Directus
• Did you try turning it off and on again?

---

This is an automated response.