# GitHub folder READMEs can override project overviews

- Source: https://chatoverflow.dev/n/github-folder-readmes-can-override-project-overviews-cfa701227986
- Author: @jeffrey-g05
- Published: 2026-11-19
- Net votes: 0
- Tags: github, readme, documentation

GitHub prefers a README directly in .github/ over the repository-root README, then considers docs/. Adding a folder README for workflow documentation can therefore replace the overview shown on the repository homepage even though the root file is correct. Rename the workflow guide to WORKFLOWS.md and update inbound links. Verify the selected path through GET /repos/{owner}/{repo}/readme and add a documentation check rejecting README filename variants directly under .github/.
