A README.md is the first file visitors see when they open your GitHub repository. To create one, click Add file and select Create new file, type README.md as the filename, then write your project description using Markdown formatting. GitHub automatically renders your README on the repository's main page. Use headings, bullet points, links, and images to make it informative and professional.
Your README Is Your Project's Front Door
A README.md file is the most important file in any GitHub repository. It is the first thing people see when they visit your repo — GitHub automatically renders it on the main page below the file list. The ".md" extension stands for Markdown, a simple formatting language that lets you create headings, bold text, links, bullet lists, tables, and images using plain text characters. You do not need to know HTML — Markdown is designed to be readable even in its raw form. If you are building an app with AI tools like Lovable or V0, having a clear README helps collaborators (and AI agents that read your repo) understand what the project does, how it is structured, and how to use it. GitHub even provides a special rendering for README.md files: headings become clickable anchors, code blocks get syntax highlighting, and links become clickable.
Prerequisites
- A free GitHub account (sign up at github.com)
- A repository where you have write access
- An idea of what your project does (even a one-sentence summary is enough to start)
Step-by-step guide
Open your repository and start creating a new file
Open your repository and start creating a new file
Go to your repository on github.com. If your repo does not have a README yet, you may see a green "Add a README" button at the bottom of the page — click it for a shortcut. Otherwise, click the green "Add file" button near the top-right of the file list and select "Create new file" from the dropdown.
Expected result: You see the new file editor with an empty filename field and code editor.
Name the file README.md
Name the file README.md
In the filename field at the top, type "README.md" (the capitalization matters — GitHub recognizes README.md, Readme.md, and readme.md, but README.md is the convention). As soon as you type the .md extension, GitHub enables Markdown preview mode.
Expected result: The filename field shows README.md and the Preview tab appears next to the Edit tab.
Write your project title and description
Write your project title and description
In the editor, start with a heading by typing a hash symbol followed by a space and your project name: "# My Project Name". Press Enter twice to start a new paragraph, then write 1-3 sentences describing what your project does. Use plain, clear language. For example: "A task management app built with React and Supabase that helps small teams track their daily work."
Expected result: You have a title heading and a project description in the editor.
Add sections using Markdown formatting
Add sections using Markdown formatting
Build out your README with useful sections. Use double hash (##) for section headings. Common sections include: ## Features (bullet list of what the app does), ## Getting Started (how to use it), ## Tech Stack (tools and frameworks used), and ## Contributing (how others can help). For bullet points, start each line with a hyphen and a space (- item). For numbered lists, use numbers (1. First step). For links, use [link text](URL). For code snippets, wrap text in backticks (`code`).
1# My Project Name23A task management app for small teams.45## Features67- Create and assign tasks to team members8- Set due dates and priority levels9- Real-time updates powered by Supabase10- Mobile-friendly responsive design1112## Tech Stack1314- **Frontend**: React + TypeScript + Tailwind CSS15- **Backend**: Supabase (PostgreSQL, Auth, Realtime)16- **Built with**: [Lovable](https://lovable.dev)1718## Getting Started1920Visit [our live app](https://example.com) to create an account.2122## License2324MITExpected result: Your README has multiple sections with formatted content.
Preview your README before committing
Preview your README before committing
Click the "Preview" tab at the top of the editor (next to the "Edit" tab). GitHub renders your Markdown so you can see exactly how it will look on your repository page. Check that headings are the right size, links are clickable, bullet points render correctly, and bold text appears bold. Click back to the "Edit" tab to make any corrections.
Expected result: The Preview tab shows your README rendered with proper formatting — headings, lists, links, and bold text all display correctly.
Commit the README file
Commit the README file
Click the green "Commit changes..." button in the top-right corner. In the dialog, type a commit message like "Add project README with description and tech stack." Select "Commit directly to the main branch" and click "Commit changes." Go back to your repository's main page — your README now appears below the file list, fully formatted.
Expected result: Your README.md is visible on the repository's main page, rendered with all your Markdown formatting.
Complete working example
1# TaskFlow23A simple task management app for small teams built with React and Supabase.4567## Features89- Create, edit, and delete tasks10- Assign tasks to team members11- Set priorities: Low, Medium, High, Urgent12- Real-time updates — changes appear instantly13- Filter tasks by status, assignee, or priority1415## Tech Stack1617| Technology | Purpose |18|------------|----------|19| React 18 | Frontend framework |20| TypeScript | Type safety |21| Tailwind CSS | Styling |22| shadcn/ui | UI components |23| Supabase | Database, Auth, Realtime |2425## Getting Started26271. Visit [taskflow.example.com](https://taskflow.example.com)282. Sign up with your email293. Create your first project304. Invite your team members3132## Contributing3334We welcome contributions! Please open an issue first to discuss changes.3536## License3738MIT License — see [LICENSE](LICENSE) for details.Common mistakes when creating a README File in GitHub
Why it's a problem: Forgetting to add a space after the hash (#) for headings
How to avoid: Markdown requires a space after the hash: "# Heading" works, "#Heading" does not. Always add a space.
Why it's a problem: Writing a README that only says "My project" with no useful information
How to avoid: Include at minimum: what the project does, what technology it uses, and how to get started. Even two paragraphs are better than nothing.
Why it's a problem: Using a single hash (#) for all headings
How to avoid: Use # for the main title, ## for sections, and ### for subsections. This creates a proper visual hierarchy.
Why it's a problem: Not previewing before committing and ending up with broken formatting
How to avoid: Always click the Preview tab to check your Markdown renders correctly before committing.
Best practices
- Start with a clear one-line description of what the project does.
- Include a Features section with bullet points highlighting key capabilities.
- Add a Tech Stack section so visitors know what technologies the project uses.
- Use a table for structured information like tech stack or configuration options.
- Include a screenshot or demo GIF to show what the app looks like.
- Keep the README updated as the project evolves — stale READMEs confuse visitors.
- Add badges for build status, license, or version if your project uses CI/CD.
- Link to additional documentation if the README grows too long.
Still stuck?
Copy one of these prompts to get a personalized, step-by-step explanation.
Write a professional README.md for my GitHub repository. The project is a [describe your app] built with React, Supabase, and Tailwind CSS using Lovable. Include sections for features, tech stack, getting started, and contributing.
Frequently asked questions
Does the file have to be called README.md exactly?
GitHub recognizes README.md, Readme.md, and readme.md, but the convention is README.md in all caps. GitHub also supports README.rst (reStructuredText) and README.txt (plain text), but Markdown is by far the most common.
Can I add images to my README?
Yes. Upload an image to your repository (e.g., in a public/images/ folder), then reference it in Markdown with . You can also paste an image URL from an external host.
How do I add a table of contents to my README?
GitHub automatically generates anchor links for headings. You can create a manual table of contents using links like [Features](#features) that jump to the ## Features heading. Heading text is lowercased and spaces become hyphens.
Will AI tools like Lovable or Cursor read my README?
Yes. AI tools that connect to your GitHub repo often read the README to understand the project context. A clear README helps these tools generate more accurate code and suggestions.
Can I use HTML inside my Markdown README?
Yes. GitHub Markdown supports a subset of HTML. You can use tags like <details> for collapsible sections, <img> for more control over images, and <table> for complex layouts. However, plain Markdown is preferred for readability.
Can RapidDev help me write a professional README for my project?
Yes. RapidDev helps non-technical founders create polished project documentation, including README files, contributing guides, and architecture diagrams that make your repo look professional and inviting to collaborators.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation