Writing a README

A README is the first thing anyone sees when they visit your GitHub repository. GitHub automatically renders README.md on the repository’s front page. For a portfolio project, the README is your opportunity to explain what the project is, what you built, and what skills it demonstrates.

What a good README includes

Project name and description — One or two sentences on what the project is. Someone who has never seen it should understand immediately.

Screenshot or demo link — A visual of the project makes an enormous difference. Employers scroll through dozens of repositories. A screenshot stops them.

What it is built with — List the technologies. For STO: HTML, CSS, JavaScript, no frameworks. State that explicitly — “vanilla” work demonstrates fundamentals.

What you learned or practiced — This is the part that makes a student project useful in a portfolio. Employers know you were learning. Showing that you know what you learned is more honest and more interesting than pretending the project is production code.

How to run it locally — Instructions for viewing the project. For a static site, this is simple: “Open index.html in a browser” or “Use a local server.”

Project structure — A short overview of the files and directories helps anyone navigating the code.

The STO README

Create README.md in the project root:

# Summit Trail Outfitters

A static website for a fictional hiking gear and trail guide company,
built as a capstone project for an HTML, CSS, and JavaScript learning path.

## Live Site

[View on GitHub Pages](https://yourusername.github.io/summit-trail-outfitters/)

*(Link goes live after the next lesson — enabling GitHub Pages.)*

## What I built

- 6-page static site: Home, About, Contact, Trails, Gear, 404
- Responsive layout using CSS custom properties and Flexbox
- Contact form with real-time validation in vanilla JavaScript
- Trail and gear listings using consistent card components
- Custom 404 page

## Technologies

- HTML5 (semantic elements, form validation attributes)
- CSS3 (custom properties, Flexbox, media queries)
- JavaScript (DOM manipulation, form validation, no frameworks or libraries)

## What I practiced

- Structuring a multi-page site with shared navigation
- Building a design system with CSS custom properties (color, type, spacing)
- Writing accessible HTML (proper heading hierarchy, label/input associations, alt text)
- JavaScript form validation with real-time feedback
- Git version control and GitHub workflow

## Project structure

summit-trail-outfitters/ ├── index.html ├── about.html ├── contact.html ├── trails.html ├── gear.html ├── 404.html ├── css/ │ └── style.css ├── js/ │ └── main.js └── images/

## How to view locally

Open `index.html` in any modern browser. No build step or server required.

Customizing for your project

Edit the README to match your actual project:

• Replace yourusername with your GitHub username
• Update the “What I built” list to match the features you actually implemented
• Adjust the file structure if yours differs
• Add or remove technologies as appropriate

Commit the README

git add README.md
git commit -m "Add README with project description and structure"
git push

Visit your GitHub repository. The README now renders on the front page below the file listing.

Screenshots (optional but recommended)

To add a screenshot:

1. Take a screenshot of the STO home page
2. Save it as screenshot.png in the repository root (or in an images/ folder)
3. Add it to the README above the description:

![Summit Trail Outfitters homepage](screenshot.png)

4. Commit and push the screenshot along with the updated README

A screenshot is one of the highest-value things you can add to a portfolio project’s README. It takes two minutes and substantially increases the chance that someone looking at your profile will click into the repository.

Exercise

1. Create README.md in your STO project root using the template above. Edit it to accurately describe your project.

2. Stage, commit, and push:

git add README.md
git commit -m "Add README with project description and structure"
git push

3. Visit your GitHub repository in a browser. Confirm the README renders correctly below the file list.

4. Optional: add a screenshot and push it.

Recap

• README.md renders automatically on the GitHub repository front page.
• A good portfolio README covers: what the project is, what it is built with, what you learned, and how to run it.
• Be specific about what you built and practiced — honest self-assessment is more useful than generic claims.
• A screenshot takes two minutes and significantly increases engagement with your project.
• Commit and push README.md the same way as any other file.

Next: tagging a release — marking the current state of the project as a specific version.