How to Write Markdown in a GitHub README File

Navigate to your repository on github.com. If a README.md file already exists, you'll see its rendered content at the bottom of the file list. Click the pencil icon in the top-right corner of the README section to edit it. If no README exists, click the "Add file" dropdown above the file list and select "Create new file." Type "README.md" in the filename field. The .md extension tells GitHub this is a Markdown file.

Headings use the # symbol. One # creates the largest heading (H1), ## creates a medium heading (H2), and ### creates a smaller heading (H3). Always put a space between the # and your text. For example, type "# My Project" on the first line for the main title. On the next line, add "## About" for a section heading. Then add "### Features" for a subsection. A good README structure is: project name (H1), description paragraph, About (H2), Features (H2), Getting Started (H2), and Contact (H2).

Wrap text in double asterisks for bold: **important text** renders as bold. Use single asterisks for italics: *emphasized text*. For links, use the format [display text](URL) — for example, [Visit our site](https://example.com). You can combine these: **[Bold link](https://example.com)**. To add a horizontal line to separate sections, type three dashes on their own line: ---. These formatting tools let you highlight key information and link to external resources like your deployed app URL or documentation.

For bullet lists, start each line with a dash and a space: "- First item" on one line, "- Second item" on the next. For numbered lists, use "1. First item" and "2. Second item." GitHub also supports task checklists using "- [ ] Unchecked task" and "- [x] Completed task" — these render as clickable checkboxes, which are great for tracking project progress. Leave a blank line before and after any list to ensure proper formatting. Nested items get two spaces of indentation before the dash.

For inline code (small snippets within a sentence), wrap the text in single backticks: `npm run build` renders as a code-formatted snippet. For multi-line code blocks, use triple backticks on the line before and after your code. You can also specify the language after the opening backticks for syntax highlighting — for example, type three backticks followed by "typescript" on the first line, then your code, then three closing backticks. This is especially useful for documenting setup commands or code snippets generated by AI tools like Cursor or Lovable.

Tables use pipes (|) and dashes (-). The first row is the header, the second row is a separator line of dashes, and subsequent rows are data. For example: "| Feature | Status |" on line one, "| --- | --- |" on line two, and "| User login | Done |" on line three. Each column is separated by a pipe character. Tables are perfect for showing tech stack details, feature lists, or comparison charts. Keep tables simple — three to four columns maximum for readability.

Click the "Preview" tab at the top of the GitHub editor (next to the "Edit" tab). GitHub will render your Markdown into formatted text so you can see exactly how it will look to visitors. Check that headings are the right size, links are clickable, code blocks are formatted, and tables are aligned. If anything looks off, switch back to the Edit tab and fix it. Once you're satisfied, click the green "Commit changes" button. Add a commit message like "Update README with project documentation" and click "Commit changes" in the dialog.