Markdown README template: a project's first working command

A Markdown README template gives a project a front door. Someone opening the folder should be able to find what the project does, what they need before starting and a command they can run to see it work. Keep that page as README.md directly inside the project folder.

The template below covers that first visit. It includes an empty starting block, a filled example and guidance for keeping the page accurate as the project changes. Unsure about the extension? See the meaning of .md.

What a project README answers

A README stays with a project through its working life. It describes the project as it exists today and gives a newcomer a short route into using it. That applies to a private folder shared with a few authorized people as well as a public project.

The first command is a small proof that the reader can use the project. Give it a starting folder and an expected result. A command without either leaves someone wondering where to type it or whether it worked.

Keep future work agreements elsewhere. A README describes the current project; it doesn't settle the scope of a job that has yet to begin. It can point a person toward deeper instructions later, but this entry page should get them through their first run.

The README template

Create README.md in your project folder and paste this block into it. Replace the prompts with the details of your own project. Command placeholders describe what to write; they aren't commands to run as written.

# Project name

Describe what this project does and who it is for.

## Prerequisites

- Name the tools and versions needed before starting.
- State any access permission or local files the reader needs.

## Setup

1. Explain how to obtain an authorized copy of this project folder.
2. Give the setup actions in order, including any commands.
3. Say which folder to open before the first run.

## First run

Write the first command here, exactly as the reader should type it.

## Expected result

Describe the output or visible change produced by that command.

## Known limits

- State a current restriction on what the project does.
- Name an input or situation the first run does not cover.

## Project contact

Name the person who can answer questions about this project.

Purpose comes before prerequisites so someone can decide whether they have the right project. Prerequisites name what has to be ready before setup begins. Put access requirements there too: a private project may require permission before the reader can obtain its files.

Setup describes preparation for this project, including any required installation. First run then gives one small action using the prepared project. Expected result tells the reader what success looks like, while Known limits names boundaries that a successful first run doesn't prove away.

Give each heading a blank line before its text begins, and separate paragraphs with blank lines too. Read about paragraph gaps in Markdown to see their effect on the rendered page.

A filled README for Doe Holdings

This fictional project contains a small program that totals whole-number item counts. Jane Doe is its contact at the invented Doe Holdings. The folder, program and output below are invented to show how a README describes an existing project; the program itself isn't included in this post.

# Doe Holdings item total

This project adds whole-number item counts from a local text file. It is for staff who need a total for a small batch of items.

## Prerequisites

- Python 3.11 or later is already on your computer.
- Jane Doe has given you permission to use the project folder.
- Your copy contains total.py and sample-counts.txt.

## Setup

1. Get the item-total folder from Jane Doe through the firm's approved shared folder.
2. Open a terminal in item-total, where total.py and sample-counts.txt sit.
3. Use the included sample-counts.txt unchanged for the first run. It contains three lines: 4, 7 and 2.

## First run

From the item-total folder, run: python3 total.py sample-counts.txt

## Expected result

The terminal displays Total: 13. The program leaves sample-counts.txt unchanged.

## Known limits

- The program accepts one whole number per line.
- Decimal values and negative values are rejected.
- This first run uses only the included sample file.

## Project contact

Jane Doe answers questions about the item-total project at Doe Holdings.

The example names the required runtime before any command appears. Its setup puts the reader in the folder containing both named files. The command uses the included input, and the expected result gives an exact total, rather than asking someone to decide whether the output looks right.

For your own project, use a small input that is safe for an authorized new reader to try. Say whether the command changes files or other state. If it needs private credentials, describe how an authorized person obtains them without putting their values in the README.

Place README.md beside the project files

Save README.md directly inside the project's main folder. For the fictional example, that means item-total/README.md, beside total.py and sample-counts.txt. A reader opening item-total can find the starting page without searching deeper folders.

Keep the entry file's name steady as its text changes. For broader choices, see how to name Markdown files. Here, README.md identifies the project's starting page, so it doesn't need a date or a new filename for each revision.

After changing setup or the program's behavior, walk through the README from a fresh authorized copy. Compare the prerequisites with what that copy needs, run the written command from the stated folder and compare its output with Expected result. Revise Known limits when a restriction changes.

Keep one current entry page in that location. Separate copies named README-new.md or README-final.md leave the next person choosing which instructions to trust. Edit the existing page so the next visit begins with the current steps.

Where Sashmark fits

A README may be your first stop among Markdown files written by an AI agent. For people handling that writing on their desktop, Sashmark remains in development. The app's intended role here is opening a README for reading or edits; run your project's commands outside it.