Changing an article's title

When it's necessary to change the title of an article, the name may need to be updated in several places.

In this article

Changing the title of an article

Sometimes, it's necessary to change the title of a help article. There are several considerations to keep in mind when you retitle an article.

Background on changing the filename

The title of the article corresponds directly to the name of the Markdown file that contains that article, for a couple of reasons:

  • SEO: When we use real words that correlate to the content of the article in a URL, our articles are weighted more heavily for search engines. For more information, see "Improve the structure of your URLs" in the Google Search Engine Optimization Starter Guide.

Places you should consider updating when you change a title

There are several places you may need to update when you give an article a new title.

Frontmatter and metadata section

Each article contains a metadata section or frontmatter located at the top of the article formatted using YAML syntax. This metadata section generates the title of the article and contains other important data, such as redirects and sometimes even short description conrefs that link to reusable intro text.

---
title: Your article name
intro:
redirect_from:
  - /articles/older-outdated-article-name/
---

Frontmatter update checklist

  • Update title using sentence case
  • Update redirects. Almost every time we retitle an article, we should add a redirect referencing the article's old URL and make sure we keep any redirects in the old article's frontmatter.

Filename

You can use the git mv command in your terminal to change the name of the file.

$ git mv old-article-name.md new-article-name.md

Parent index file

Make sure to update the link to the file in its parent index.md file, which generates the TOC.

We link between articles in our documentation. We recommend searching for both the filename and title to find links to update.

Search in product for links to the old title. If you find any outdated links, contact the relevant team or engineers to let them know the link has changed and ask them to update it. If you're not sure who to contact, you can ask a member of the GitHub Docs team. As a courtesy, you can also create a pull request with the updated links and ask the relevant team to merge it after the updated article title ships.