Reference component issues

[DannyBen]

I am trying to test retype as a documentation solution for my company, and encountering some annoyances.

The ref component is important to me in this context, and it has a couple of issues.

Issue 1: The link in this component is absolutely a deterrent for using this component - but I already mentioned it here: #105

Issue 2: As I have pages with spaces in their name, I cannot seem to get the reference to show properly.

1. The filename itself and its H1 is "Information Security Management System (ISMS)" - as it properly appears in the sidebar
2. The ref result is showing the kebab-cased name, and not its H1
3. I would like to have this component show a "human friendly path" like in circled point 3

I know I can use label metadata, but this information is redundant to me and therefore I would like to avoid it - the filename and H1 both already have the label I want.

Is there any way for me to fix it (outside of adding a label)?
If not - is this component planned for an upgrade in Retype's roadmap?

[geoffreymcgill]

2. The ref result is showing the kebab-cased name, and not its H1

Can you recheck this sample using v2.4.0?

When I test locally using v2.4.0, the correct label appears to be is used.

3. I would like to have this component show a "human friendly path" like in circled point 3

I'm looking into some options and will likely handle those changes in #105.

[DannyBen]

Same problem.

See this minimal retype folder: 📁 retype-issue.zip

Which converts this:

# Welcome

## PASS

[!ref](/kebab-filename)
[!ref](/filename)

## FAIL

[!ref](/spaced-filename)

to this:

[geoffreymcgill]

Thanks for the sample project. I was able to reproduce the defect. We will fix and include in the next release of Retype.

[geoffreymcgill]

The path in your [!ref](/spaced-filename) sample has triggered some discussion internally and we're not 100% certain on how we're going to proceed.

The issue boils down to the different between how Retype resolves a File Path vs URL.

In your sample, the /spaced-filename is considered by Retype to be a URL as it does not point to file. Because the location is not a File Path, Retype then does not resolve to find and use the page label.

According to the CommonMark spec, if a path (uri) contains spaces, then the path must be enclosed in <> angle brackets.

If the destination contains spaces, it must be enclosed in pointy braces:

See https://spec.commonmark.org/0.18/#example-398

Ideally, your link should be revised to [!ref](</Spaced Filename.md>) as the following sample demonstrates:

[!ref](/spaced-filename)

[!ref](</Spaced Filename.md>)

The following Ref component is then created:

The question is then if we should be resolving what Retype considers URL's. Resolving creates some complicated and annoying problems, so we're just walking through some options before committing to a direction.

Hope this helps.