Fix README links relative to the file that contains them. A link that works in the repository root can break when a teammate moves the instructions into docs.
Suppose your hackathon repository contains a root README, a setup guide and a screenshot. The files exist, but the setup guide points to the screenshot as if it were still in the root. This is a path-resolution error, not a missing image.
Draw the small directory tree
Write down the actual locations before editing links:
project/
README.md
docs/
setup.md
assets/
demo.png
In the root README, these relative references start from the root README's directory:
[Setup guide](docs/setup.md)
Inside docs/setup.md, start from docs instead:
[Project overview](../README.md)
The first .. means move up one directory before entering assets. GitHub's Markdown documentation explains that relative links resolve from the current file, while a leading slash resolves from the repository root on GitHub. That leading-slash behavior should not be assumed for every local Markdown viewer.
Check the rendered file in two places
Open the root README on the branch you will submit. Follow the setup link and inspect the image in the setup guide. Then open both Markdown files in the local viewer your teammate actually uses. The two renderers may handle repository-specific links differently, so record which views you checked.
Keep filenames and capitalization consistent with the tracked files. Also check the file extension. A link ending in demo.jpg cannot refer to a file actually named demo.png merely because they contain similar pictures.
Use a repository-relative path for a file that should travel with the checkout. Use a full public URL for an external service. Avoid absolute paths from your own laptop, such as a desktop folder. Another person's machine has no reason to contain that location.
Separate file paths from command locations
Markdown link resolution and shell command resolution are different questions. If the guide says to run a command from the repository root, state that working directory explicitly. Do not assume that opening docs/setup.md changes where the terminal executes commands.
After moving a guide, review links in both directions. The guide's outbound paths may need an extra ..; the root README's link to the guide may need a new directory name. Keep the screenshot alt text about what the image conveys, rather than repeating its filename.
Before selecting an event from the Stavleak hackathon catalogue, prepare a small submission guide another person can navigate. The useful check is concrete: a teammate can reach the setup instructions and see the referenced screenshot from the submitted branch and their local checkout.
Top comments (0)