README essentials
Markdown for your GitHub README
Turn plain text into a profile people can scan. Start with a few useful patterns, then make the content your own.
Prefer visual editing? Start with a preset in the README builder, add your tech icons, and export your Markdown. Choose Blank when you want to write the full document yourself.
Headings
Use a clear hierarchy for your profile and project sections.
Markdown
# Maya Chen
## About me
### Current project
#### Tools
##### Notes
###### DetailsPreview
About me
Current project
Tools
Notes
Details
Text formatting
Emphasize the details readers should notice first.
Markdown
I build **accessible interfaces** with *thoughtful motion*.
~~Old portfolio~~ New projects coming soon.
My favorite command is `npm run dev`.Preview
I build accessible interfaces with thoughtful motion.
Old portfolio New projects coming soon.
My favorite command is npm run dev.
Paragraphs and line breaks
Separate paragraphs with a blank line. For a deliberate line break, end a line with a backslash.
Markdown
Frontend developer based in Lisbon.
Currently building a small weather app.
Open to collaboration.\
Especially on accessibility tools.Preview
Frontend developer based in Lisbon.
Currently building a small weather app.
Open to collaboration.
Especially on accessibility tools.
Links
Use descriptive link text. Relative paths point to files in your repository.
Markdown
[Explore the icon library](/)
[Read the project notes](./docs/notes.md)
[Jump to my projects](#projects)Preview
Explore the icon library
Read the project notes
Jump to my projects
Preview links above are examples. Replace placeholder paths and section anchors with destinations in your own README.
Lists and task lists
Group related skills or show progress on a project.
Markdown
- TypeScript
- React
- Component libraries
- Design systems
1. Choose a project
2. Add a description
3. Share the result
- [x] Build the prototype
- [ ] Write the documentationPreview
- TypeScript
- React
- Component libraries
- Design systems
- Choose a project
- Add a description
- Share the result
- Build the prototype
- Write the documentation
Quotes and dividers
Use a quote for a short note and a divider to separate sections.
Markdown
> Small improvements add up.
---
Ready for the next project.Preview
Small improvements add up.
Ready for the next project.
Code blocks
Wrap a snippet in triple backticks. Add a language name such as javascript, python, or bash for highlighting on GitHub.
Markdown
```javascript
const greeting = "Hello, developer!";
console.log(greeting);
```Preview
const greeting = "Hello, developer!";
console.log(greeting);
Images and tech icons
Give images useful alternative text. Save the icon in your repository before using a relative path.
Markdown
Preview
This preview uses a hosted React icon. For theme-aware icon markup and sizing, use the builder’s generated output.
Tables
Keep tables small enough to read on a phone.
Markdown
| Project | Built with | Status |
| --- | --- | --- |
| Weather journal | React | Live |
| Color explorer | TypeScript | In progress |Preview
| Project | Built with | Status |
|---|---|---|
| Weather journal | React | Live |
| Color explorer | TypeScript | In progress |
Literal characters
Escape punctuation when you want the characters to appear as text.
Markdown
\*This is not italic\*
\# This is not a headingPreview
*This is not italic*
# This is not a heading
Put your README together
Introduce yourself, highlight a few projects, then add your tools and contact links. Preview your exported file on GitHub before publishing, especially images and relative paths.
Build your README or follow our guide to adding tech stack icons.
These examples focus on README files. Rendering can differ between our preview and GitHub. For the full reference, see GitHub’s writing and formatting documentation.