Normalize Sample Code URLs

[marinaaisa]

Bug/issue #165347857, if applicable:

Summary

We want to normalize Sample Code URLs, by adding the baseUrl to them if the path is relative and the baseUrl is provided. If the path is absolute or the baseUrl is not provided, it does not prefixes the URL.

Because the component CallToActionButton.vue is not only being used for Sample Code links, we created a new prop called linksToAsset that will normalize the relative URLs, in the cases that they are assets, like Sample Code.

Dependencies

NA

Testing

Steps:

1. Provide a baseUrl
2. Go to a page for Sample Codes that points to a relative path
3. Assert that the link gets prefixed with the baseUrl

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran npm test, and it succeeded
• Updated documentation if necessary

[mportiz08]

Do we even need to check for special flags or absolute URLs as a special case here? I think the logic should pretty much match up with the logic in components for image and video assets, which always "normalize" the URLs. I think the normalizePath function should already be a noop for absolute URLs, and I don't think there's any special logic for assets vs documents with regards to a custom base path.

[marinaaisa]

For the normalizePath function to work, the path needs to be relative. This means that we need to normalize the relative path first, to make sure that the normalizePath function reads it as a relative path.

An example is the simpleRelativePath const that I wrote in the tests, which value is foo/bar:
foo/bar needs to be normalize as a relative path to become /foo/bar instead.
Otherwise normalizePath will think that foo/bar is an absolute URL and it won't prefix the baseUrl.

The reason why I'm exiting early in the case of being a real absolute URL (by using the isAbsoluteUrl function) is that, if we pass an absolute URL to normalizeRelativePath, it will turn it into a relative path like /website.com/samplecode and then normalizePath will prefix that path as baseUrl/website.com/samplecode. We want to prevent this scenario.

[marinaaisa]

An alternative to this is to use the isAbsoluteUrl function within the normalizeRelativePath, so we will never accidentally turn an absolute URL into a relative path.

[mportiz08]

The reason why I'm exiting early in the case of being a real absolute URL (by using the isAbsoluteUrl function) is that, if we pass an absolute URL to normalizeRelativePath, it will turn it into a relative path like /website.com/samplecode and then normalizePath will prefix that path as baseUrl/website.com/samplecode. We want to prevent this scenario.

I don't think that's an issue for the existing normalizePath function or we would have hit similar issues with external image/video assets where we already call this function on all URLs.

Here's an example unit test showing the expected behavior for this function when called with an absolute URL:

swift-docc-render/tests/unit/utils/assets.spec.js

Line 68 in c781d37

it('does not change, if passed a url', () => {

[marinaaisa]

The test is showing the expected behaviour for absolute URLs (like website.com/samplecode), but by normalising the relative path it adds a slash in the URL (like /website.com/samplecode) and we want to prevent this.

This works for images and videos, because we expect the relative path to always be correct. So we don't normalise the relative path.

[mportiz08]

The test is showing the expected behaviour for absolute URLs (like website.com/samplecode), but by normalising the relative path it adds a slash in the URL (like /website.com/samplecode) and we want to prevent this.

An absolute URL should have a scheme like https://website.com/samplecode.

This works for images and videos, because we expect the relative path to always be correct. So we don't normalise the relative path.

We do already normalize relative paths for images/videos in that function by prepending the base URL (example). Absolute URLs with a scheme would be unaffected by this normalizePath function as shown in the above linked unit test.

I think the confusion is that we also have a different normalizeRelativePath function (seen below in those tests) which normalizes relative paths to all be root relative (some/path => /some/path).

We can utilize both here as you've done, although it's slightly unfortunate if we're getting different styles of relative paths for sample code when compared to images/videos in the JSON.

[marinaaisa]

@swift-ci test