thanos-io / thanos

docs: link paths differ on 'tip' vs 'v0.xx'

Summary of Open Issue: Inconsistent Documentation Link Paths in Thanos

Issue Identifier: docs: link paths differ on 'tip' vs 'v0.xx'

Reported by: wbh1 (2023-11-10)

Context: The issue pertains to inconsistencies in URL structures for documentation links between the “tip” version and stable releases of the Thanos project (specifically versions ≥ v0.30).

Observed Behavior:

  • Links for documentation on the website show a discrepancy. For instance:
  • tip: https://thanos.io/tip/proposals-done/202004-embedd-cortex-frontend.md/
  • Version v0.32: https://thanos.io/v0.32/proposals-done/202004-embedd-cortex-frontend/ (missing .md suffix)
  • Prior to v0.30 (up to v0.29), links maintained a consistent structure including the .md extension across releases. The inconsistency breaks links when switching between versions, impacting usability.

Code Reference: The inconsistency originates from the hugo.yaml configuration file, specifically the permalink settings for different versions. The script uses:

tip: "/:sections/:filename.md"
v0.29: "/:sections/:filename.md"
...

This results in a mismatch starting from v0.30 where the configuration diverges to exclude the .md suffix.

Implications:

  • Broken links hinder user experience, especially when documentation in components references other docs, as demonstrated with the Query Frontend flag.
  • Example: The flag in Query Frontend links to https://thanos.io/tip/proposals-accepted/202205-vertical-query-sharding.md which is dependent on the .md suffix.

Expected Outcome:

  • Standardize link structures across all versions to ensure that users can navigate documentation seamlessly without encountering broken links.

Action and Progress:

  • Contributors have discussed updating the Hugo configuration on an ongoing basis to avoid these discrepancies in future releases.
  • Multiple contributors have expressed their willingness to work on this issue, with suggestions for potential automation to keep the linking structure consistent and up-to-date.

Labels: Difficulty: Easy, Good First Issue, Help Wanted

This issue is marked for identification by contributors and should be addressed promptly to enhance user experience with Thanos documentation.