bazelbuild / bazelbuild/bazel

Bazel docs infra: stop naively converting all markdown links to html

Open
#11,405 2 comments 0 reactions 0 assignees View on GitHub
help wanted P3 team-Documentation type: documentation (cleanup)
Dominant language
Java
Stars
25.8k
Forks
4.6k
Avg merge
2d 20h
Merged PRs (30d)
72

Description

The jekyll build script below naively converts all .md links in the doc site to .html. This is desirable for most links since the doc site uses .html in URLs, but it has caused problems when the intention is to keep the .md extension. For example, when linking directly to markdown files on GitHub.

https://github.com/bazelbuild/bazel/blob/357282fa857a007555ae053afc827283a3e402d6/site/jekyll-tree.sh#L104-L111

Contributor guide

Open the contributing guide

Research direction

Start with site/jekyll-tree.sh lines 104-111, where Markdown links are converted during the Jekyll documentation build. Trace how the script distinguishes links intended to remain .md from links that should become .html. Done means the build preserves direct Markdown links while retaining the existing conversion for normal documentation links.

Written by the indexing model from the issue text.

Assessment

Tech stack
jekyll, markdown, shell
Domain
build-system, documentation
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.