From ace85189323df918f3b95a68759ddf7d115d9d7d Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 7 Aug 2025 17:17:39 -0400 Subject: [PATCH 1/4] Update README documentation --- .../customizing-your-repository/about-readmes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md index 825b4b96d414..941ad6071770 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md @@ -1,5 +1,5 @@ --- -title: About READMEs +title: Repository README file 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 @@ -14,7 +14,7 @@ versions: topics: - Repositories --- -## About READMEs +## About the repository README file {% data reusables.repositories.about-READMEs %} From b0d41732aa868e48e8d0d371bb53a0748c15e906 Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Thu, 7 Aug 2025 17:42:23 -0400 Subject: [PATCH 2/4] Work around linter --- .../customizing-your-repository/about-readmes.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md index 941ad6071770..382956240581 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md @@ -1,5 +1,6 @@ --- title: Repository README file +shortTitle: About READMEs 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 From 7062d45ea9b7769c5f757bf73ee06f18c70e241d Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Fri, 8 Aug 2025 15:36:19 -0400 Subject: [PATCH 3/4] Some improvements --- .../customizing-your-repository/about-readmes.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md index 382956240581..7747cb4ca6ef 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md @@ -1,5 +1,5 @@ --- -title: Repository README file +title: Using a repository README file shortTitle: About READMEs 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: @@ -15,7 +15,7 @@ versions: topics: - Repositories --- -## About the repository README file +## About READMEs {% data reusables.repositories.about-READMEs %} @@ -36,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 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 From d50a3c50ed284334b26dd7c8e7dd0abe98a9bfad Mon Sep 17 00:00:00 2001 From: Josh Soref <2119212+jsoref@users.noreply.github.com> Date: Mon, 11 Aug 2025 15:53:41 -0400 Subject: [PATCH 4/4] Use aspirational title --- .../customizing-your-repository/about-readmes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md index 7747cb4ca6ef..a5cee546b147 100644 --- a/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md +++ b/content/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes.md @@ -1,5 +1,5 @@ --- -title: Using a repository README file +title: About the repository README file shortTitle: About READMEs 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: