Skip to content

Update README documentation #39720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
+6 −5
Open

Update README documentation #39720

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ace8518
Update README documentation
jsoref Aug 7, 2025
b0d4173
Work around linter
jsoref Aug 7, 2025
7062d45
Some improvements
jsoref Aug 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions ...-repositorys-settings-and-features/customizing-your-repository/about-readmes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
---
title: About READMEs
title: Using a repository README file
shortTitle: About READMEs
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a hack. @Sharra-writes can fix it more properly at a later date.

This comment was marked as spam.

Sign in to view

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I looked through our "about" docs and I've realized that most of them start with a section that's "About thing." I don't love that, I think it's a little pointless, but it seems to be the format. And then I read your issue again and realized you were initially talking about changing the title. What would you think about doing that, using "About the repository README file" as the title, and leaving "About READMEs" as the section title? Alternatively, if you can come up with another/better section title, I would be very in favor of it. I was kicking around things like "Overview of READMEs" or "Purpose of a README," but I'm not sure "overview" is different enough from "about" to justify breaking the format, and the section as currently written doesn't quite fit a "purpose" heading.

In the meantime, I'm pretty sure we changed things recently so that the URL can match the short title instead of having to match the title, but I need to see if there's anything special I have to do to make that work.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The about section title is indeed annoying.

And yes, I'm more interested in changing the first title than the second. afaict the shortTitle does let me do what I need to avoid trying to rename things all over.

image

The second About READMEs is actually pretty terrible in this case given the content it "covers" (but doesn't actually cover!):

You can add a README file to a repository to communicate important information about your project. A README, along with a repository license, citation file, contribution guidelines, and a code of conduct, communicates expectations for your project and helps you manage contributions.

Effectively half of the content for the first paragraph in the section has nothing to do with the README file!

I considered:
## Repository Overview

Which might properly cover what's in that paragraph.

If you put your README file in your repository's hidden .github, root, or docs directory, GitHub will recognize and automatically surface your README to repository visitors.

This sentence might not be technically wrong, but I read it as:

  • If you put your README file in your repository's hidden .github directory; or
  • If you put your README file in your repository's hidden root directory; or
  • If you put your README file in your repository's hidden docs directory;
    ...

which isn't what the author was trying to say. I have to endorse your plan to make rewriting this file a project to do very soon.

This paragraph needs a section heading so it can have an anchor:

If you add a README file to the root of a public repository with the same name as your username, that README will automatically appear on your profile page. You can edit your profile README with GitHub Flavored Markdown to create a personalized section on your profile. For more information, see Managing your profile README.

https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes#relative-links-and-image-paths-in-readme-files

Your link text should be on a single line. The example below will not work.

[Contribution
guidelines for this project](docs/CONTRIBUTING.md)

I hope that statement was correct at some point, but regardless, it doesn't appear to be correct today:

https://github.com/check-spelling-sandbox/ideal-eureka-effective-guacamole?tab=readme-ov-file

https://raw.githubusercontent.com/check-spelling-sandbox/ideal-eureka-effective-guacamole/refs/heads/prerelease/README.md

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm actually struggling w/ a title for the document.

I considered:

title: About the repository README file

But, I don't think that's really what this document is about.

It's more like "What to put into a repository README file, where to put it, and how it will be seen"

How about:

title: Using a repository README file

That isn't wrong, the document does help you use one. It helps you know where to put it, it helps you know what to put in it, and it helps you understand how others will use/experience it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fwiw, I've reverted me change to the ## About READMEs -- I can't think of any good way to handle that, and the page title is more important/problematic than the first item in it, even though that's clearly a mess. 🤷‍♂️

intro: 'You can add a README file to your repository to tell other people why your project is useful, what they can do with your project, and how they can use it.'
redirect_from:
- /articles/section-links-on-readmes-and-blob-pages
Expand Down Expand Up @@ -35,25 +36,25 @@ When your README is viewed on GitHub, any content beyond 500 KiB will be truncat

{% data reusables.profile.profile-readme %}

## Auto-generated table of contents for README files
## Auto-generated table of contents for markdown files
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this page has a ToC that's automatically displayed, I see no reason for the section titles to say README when the section content clearly says "well, actually, any markdown file".

image


For the rendered view of any Markdown file in a repository, including README files, {% data variables.product.github %} will automatically generate a table of contents based on section headings. You can view the table of contents for a README file by clicking the {% octicon "list-unordered" aria-label="Table of Contents" %} menu icon at the top left of the rendered page.

![Screenshot of the README for a repository. In the upper-left corner, the "Table of contents" dropdown menu (list icon) is expanded.](/assets/images/help/repository/readme-automatic-toc.png)

## Section links in README files and blob pages
## Section links in markdown files and blob pages

{% data reusables.repositories.section-links %}

For more detailed information about section links, see [Section links](/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#section-links).

## Relative links and image paths in README files
## Relative links and image paths in markdown files

{% data reusables.repositories.relative-links %}

## Wikis

A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/about-wikis).
A README should only contain information necessary for developers to get started using and contributing to your project. Longer documentation is best suited for wikis. For more information, see [AUTOTITLE](/communities/documenting-your-project-with-wikis/about-wikis).

## Further reading

Expand Down
Loading