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.
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.
There are several places you may need to update when you give an article a new title.
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/
- 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.
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
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.