At the time of this writing, our resource_link shortcode can produce two types of output.
HTML for external-resources
Markdown for other types of links
Studio uses this shortcode with {{% tags i.e {{% resource_link ... %}}. {{% syntax processes markdown content while the alternative {{< syntax does not.
The shortcode should return one kind of output so that the use of the shortcode follows a consistent syntax. Mixing the output types has the potential to cause unexpected rendering problems.
The approach we follow relies on the future of External Resources. If their UI flow changes, we might not need to change resource_link. We can use the shortcode external_resource_link instead. However, if the UI flow remains the same, we will need to update the resource_link shortcode to return only HTML and update all of its usage.
Description/Context
At the time of this writing, our
resource_linkshortcode can produce two types of output.external-resourcesStudio uses this shortcode with
{{%tags i.e{{% resource_link ... %}}.{{%syntax processes markdown content while the alternative{{<syntax does not.The shortcode should return one kind of output so that the use of the shortcode follows a consistent syntax. Mixing the output types has the potential to cause unexpected rendering problems.
For information on the issues we have faced, you may read https://github.com/mitodl/ocw-hugo-themes/pull/1371#discussion_r1537439236. And for more details about the issue itself, you may read this excellent explanation by @gumaerc.
Plan/Design
The approach we follow relies on the future of External Resources. If their UI flow changes, we might not need to change
resource_link. We can use the shortcodeexternal_resource_linkinstead. However, if the UI flow remains the same, we will need to update theresource_linkshortcode to return only HTML and update all of its usage.(Originally proposed in https://github.com/mitodl/ocw-hugo-themes/pull/1371#discussion_r1538184588)
The latter will require the following steps:
resource_linkto return only HTML.{{< resource_link ... >}}syntax.