docs-content icon indicating copy to clipboard operation
docs-content copied to clipboard

Replace links to ephemeral file URLs with persistent "resource" links

Open per1234 opened this issue 1 year ago • 0 comments

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 the static folder at the time of publishing. In addition to the files that are hosted in the repository's static folder, the repository infrastructure also finds all files under the content/hardware folder with suffix matching standardized patterns used by the common product "resource" files and copies them to the appropriate locations under the static folder before publishing the website:

https://github.com/arduino/docs-content/blob/108ee822081769ccbf7d357cb7a73bf9c7f89e06/.github/workflows/cloudflare.yml#L29-L35

(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:

  • Link to full URL e.g.:
    [Portenta C33 schematics](https://docs.arduino.cc/resources/schematics/ABX00074-schematics.pdf)
    
  • Domain-less link e.g.:
    [Portenta C33 schematics](/resources/schematics/ABX00074-schematics.pdf)
    

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: https://github.com/arduino/docs-content/pull/1881#discussion_r1568782232

per1234 avatar Apr 19 '24 13:04 per1234