Replace links to ephemeral file URLs with relative paths #1887
Conversation
In addition to the Markdown content source files, this repository hosts non-text files. These are linked to in the content. The website publishing system hosts these non-text files in paths under the `static` subfolder of the website. The path of the published file includes the file's MD5 hash. This means that the URL will change every time the file is modified. For this reason, hardcoding links to these URLs in the content should be avoided whenever possible. The website generation system automatically replaces links to relative paths with the equivalent ephemeral URL under the `static` subfolder of the website. This means that a link to the relative path of the file is functionally equivalent to linking the hardcoded ephemeral URL. Although a relative path link is still prone to breakage if the content or target file is moved to a different location in the repository, this will probably occur less frequently than modifications to the files, making the relative path approach superior to the alternative of hardcoding the ephemeral URL.
per1234
added
enhancement
|
Hey @per1234! I've added a task to the backlog to include the STEP files into the "static resource URL" system. Until that point, it's fine for me to implement your changes - but this is up to @jcarolinares and his team since they are responsible over the content itself (since this PR is concerning Pro product line) 👍🏼 |
Yes, please proceed, Jacob will take care of the merge |
|
Taking a look at this @jhansson-ard and @per1234 These changes are not going to work until we have the relative paths for step files implemented, so I suggest to keep this pull request as a draft until then. Now it will only break even more the links. Thanks! |
There was a problem hiding this comment.
Taking a look at this @jhansson-ard and @per1234
These changes are not going to work until we have the relative paths for step files implemented, so I suggest to keep this pull request as a draft until then. Now it will only break even more the links.
Thanks!
@jcarolinares how did you determine that it doesn't work? I verified this pull request by serving the website locally with the changes proposed here and the website generation system automatically replaces the relative path with the static file path just as I described:
And those links work perfectly to download the files. |
That is a good point but I don't trust in local preview, there are technical differences between the local rendering and the cloud one. Let's wait for @jhansson-ard confirmation then about that we can proceed, I prefer to wait until Monday than work twice, thank you both! |
|
@per1234 @jcarolinares We can try this on the staging platform as well to ensure it will work in production, please use the workflow in the #prj_docs_deploy channel if you want to try it 🙏🏼 |
What This PR Changes
In addition to the Markdown content source files, this repository hosts non-text files. These are linked to in the content.
The website publishing system hosts these non-text files in paths under the
staticsubfolder of the website (e.g., https://docs.arduino.cc/static/96e7dacc4383cd4a4a928872eca9e3da/ABX00112-step.zip). The path of the published file includes the file's MD5 hash (e.g.,96e7dacc4383cd4a4a928872eca9e3da). This means that the URL will change every time the file is modified. For this reason, hardcoding links to these URLs in the content should be avoided whenever possible.The website generation system automatically replaces links to relative paths with the equivalent ephemeral URL under the
staticsubfolder of the website. This means that a link to the relative path of the file is functionally equivalent to linking the hardcoded ephemeral URL.Although a relative path link is still prone to breakage if the content or target file is moved to a different location in the repository, this will probably occur less frequently than modifications to the files, making the relative path approach superior to the alternative of hardcoding the ephemeral URL.
Contribution Guidelines
Additional Context
This proposal addresses the concern raised at #1881 (comment). An alternative solution is described at #1881 (comment).