Skip to content

🟠 Customize README.md

Now that you have your cloned version of the example project open in VS Code, it's time to start editing files.

Start by customizing the README.md to describe your project.

Step 1. Open README.md

In VS Code Explorer, click on README.md in the repository root to open it for editing.

Step 2. Review and Customize README.md

The README is the public landing page for a project on GitHub. It should explain what the project does and how to run it.

README.md files generally include the following (with some project-specific variations).

Repo Title

One top-level heading with the repository name.

Badges (Optional)

Badges are optional. If you keep them, check the links. Project-specific links should use your GitHub account and your repository name.

Project Overview

Customize the author, date, and description to reflect your project.

Developer Tools

List the developer tools (we recommend the ones used in the example).

Customize the links to use your GitHub account and your repository name.

Initial Customization

Double-check the badges, images, descriptions, and documentation links.

  • Keep content that remains accurate and relevant.
  • Update project-specific names, URLs, and descriptions.
  • Remove any content that does not apply to your project.

See Markdown Basics for help writing Markdown.

Step 3. Preview the Page

Open the Markdown preview in VS Code:

  • Windows/Linux: Ctrl + Shift + V
  • macOS: Cmd + Shift + V

Confirm the headings and links display as intended.

This is just the initial modifications. We often continue updating README.md as the project develops.

VS Code is outstanding at keeping code saved as you make changes. From the VS Code menu, select File / Autosave (if it is not already enabled).

I use it all the time, so my instructions rarely say "Save your changes" as when working in VS Code, my changes are always automatically saved. It's part of why I really like VS Code.

Verification

  • [ ] Your custom README.md exists in the project root.
  • [ ] The README describes your planned custom project (rather than the original example).
  • [ ] Project-specific links use your GitHub account
  • [ ] Project-specific links use your repository name.
  • [ ] The Markdown preview displays correctly.
  • [ ] Ensure your changes are saved.

◄ Back to 🟠 Workflow C