Replace links to ephemeral file URLs with persistent "resource" links #1886
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
What This PR Changes
In addition to the Markdown content source files, this repository hosts non-text files. These are linked to in various places in the content.
The website publishing system hosts these non-text files in paths under the
static
subfolder of the website (e.g., https://docs.arduino.cc/static/d7e16a6657c086a034a14a6619cffe7b/ABX00074-schematics.pdf). The path of the published file includes the file's MD5 hash (e.g.,d7e16a6657c086a034a14a6619cffe7b
). 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 repository contains a special
static
folder. The files under that folder are published under the root of the website, using the same paths as are present in thestatic
folder at the time of publishing. In addition to the files that are hosted in the repository'sstatic
folder, the repository infrastructure also finds all files under thecontent/hardware
folder with suffix matching standardized patterns used by the common product "resource" files and copies them to the appropriate locations under thestatic
folder before publishing the website:docs-content/.github/workflows/cloudflare.yml
Lines 29 to 35 in 108ee82
(and the same system in
.github/workflows/deploy-prd.yml
and.github/workflows/deploy-stg.yml
)In order to avoid broken links and the burden of maintaining ephemeral links, these file paths (e.g.,
/resources/schematics/ABX00074-schematics.pdf
/ https://docs.arduino.cc/resources/schematics/ABX00074-schematics.pdf) should always be targeted in links when available instead of using the ephemeral URLs.Contribution Guidelines
Additional Context
There are two different possible valid approaches for linking to these files in the content source:
e.g.:
e.g.:
My impression is that the latter is the best approach. This makes it possible to produce functional links in preview builds of the website (either through this repository's currently broken automatic preview system, or local builds) to files that are not already published on docs.arduino.cc website. For this reason, I took the domain-less approach in the changes made in this PR.
Related: #1881 (comment)