External link map for customizable documentation links in frontend repos

[sarina]

Problem statement

Currently docs links are hard-coded to docs.openedx.org; many installations may want to override one or more of these link mappings to their own help sites or internal documentation libraries.

For example, all the links in openedx/frontend-app-authoring#1757

Proposed solution

Create a helper function, getExternalLinkUrl(default_link), that reads from a json blob that specifies replacement links for existing links that individual frontend-app repos have. The json blob should be defined in a global place and is not required for deploys. It is only required if installations wish to override links.

The json blob will be in the following format:

{
   "https://docs.openedx.org/en/latest/educators/how-tos/course_development/manage_course_highlight_emails.html": "myinstance-help.edu/path/to/doc.html"
}

that is, the default link will be the key and the desired replacement is the value.

This function will live in frontend-platform, within src/config.js, next to get_config.

Alternatives considered

• Leveraging custom translations: Use the translations infrastructure to override the links within strings. This would be problematic because instances with multiple languages would potentially need to update hundreds/thousands of translations, and would fall out of sync with upstream translations and string changes.
• Leveraging plugin slots: This was not chosen because of the complexity for operators to make hundreds of plugin configs just to override links.

Support

cc @arbrandes @brian-smith-tcril @tonybusa

Whiteboard:

[wgu-taylor-payne]

assign me

[wgu-taylor-payne]

@sarina I've been thinking about how to implement this and had a couple of questions for you.

1. Just to make sure we're on the same page, by json blob, you just mean a json object that maps default URLs to custom URLs, is that right?
2. Did you envision where this URL configuration (json object) would live? Would the env.config.jsx file that is already used for custom configuration be a good place for this? Or would we want to split it out into it's own file (or have it live somewhere else)?

[sarina]

Hey @wgu-taylor-payne - I discussed this with @arbrandes who is definitely more capable of giving answers than I am :)

Adolfo could you weigh in, please?

[wgu-taylor-payne]

Actually, after looking into things further, I don't think using the env.config.[js,jsx,ts,tsx] file would be a good idea. The frontend-build config makes it so that when an env.config file is imported, but the file does not exist, it will fallback to an empty object {}. I think it would be simpler to do something similar with the external URL links, rather than trying to add that mapping to the standard config file.

[arbrandes]

@wgu-taylor-payne, this is configuration, after all, and it's why env.config.jsx exists, so I feel the best place for the JSON object to be defined is indeed env.confix.jsx.

The behavior of getExternalLinkUrl(url) should be such that if there is no external link configuration present in the config object that comes out of env.config.jsx - say, when it's empty - then it simply falls back to returning the value of the first parameter, url.