Skip to main content
Get up and running with Readme.so and create your first professional README file in just a few minutes.

​
What you’ll build

By the end of this guide, you’ll have created a comprehensive README file with multiple sections including project description, installation instructions, usage examples, and more — all without writing markdown from scratch.
1

Visit the editor

Navigate to readme-so-community.vercel.app in your web browser.
No sign-up or account creation is required. The editor is completely free and works entirely in your browser.

​
Understanding the interface

The editor has a three-column layout:
  1. Left column (Sections) — Browse and add pre-built README sections
  2. Middle column (Editor) — Edit the content of selected sections using the Monaco editor
  3. Right column (Preview) — See a live preview of your rendered README
On mobile devices, the interface adapts to a single-column layout with collapsible sections.
2

Select sections for your README

Click on any section in the left sidebar to add it to your README. Essential sections to start with:
  • Title and Description (automatically added) — Your project name and brief description
  • Installation — How to install or set up your project
  • Usage/Examples — Code examples showing how to use your project
  • Features — Key features and capabilities
  • Contributing — Guidelines for contributors
  • License — Your project’s license
Readme.so provides 30+ pre-built section templates organized by category:
  • Project Documentation: Title, Description, Logo, Screenshots, Demo
  • Setup & Installation: Installation, Run Locally, Environment Variables, Deployment
  • Usage: Usage/Examples, API Reference, Documentation
  • Testing & Quality: Running Tests, Tech Stack, Optimizations
  • Community: Contributing, Authors, Support, Feedback, Acknowledgements
  • Legal & Info: License, Badges, FAQ, Roadmap, Appendix
  • GitHub Profile: Introduction, About Me, Skills, Links
Click the + Add Section button or select from the available templates:
// Example: Adding a section programmatically (from SectionsColumn.js:92-101)
const onAddSection = (e, section) => {
  localStorage.setItem('current-focused-slug', section)
  setpageRefreshed(false)
  setAddAction(true)
  setSectionSlugs((prev) => updateSlugsOnAdd(prev, section))
  setFilteredSlugs((prev) => updateSlugsOnAdd(prev, section))
  setSelectedSectionSlugs((prev) => [...prev, section])
  setFocusedSectionSlug(localStorage.getItem('current-focused-slug'))
  resetSearchFilter()
}
3

Reorder sections with drag-and-drop

Once you’ve added multiple sections, you can reorder them by dragging and dropping in the left sidebar.The drag-and-drop functionality is powered by @dnd-kit:
// Drag-and-drop implementation (from SectionsColumn.js:107-117)
const handleDragEnd = (event) => {
  const { active, over } = event
  if (active.id !== over.id) {
    setSelectedSectionSlugs((sections) => {
      const oldIndex = sections.findIndex((s) => s === active.id)
      const newIndex = sections.findIndex((s) => s === over.id)
      
      return arrayMove(sections, oldIndex, newIndex)
    })
  }
}
Common README section ordering:
  1. Title and Description
  2. Badges (optional)
  3. Screenshots or Demo
  4. Features
  5. Installation
  6. Usage/Examples
  7. API Reference (if applicable)
  8. Contributing
  9. License
4

Edit section content

Click on any section in the left sidebar to edit its content. The Monaco editor in the middle column provides:
  • Syntax highlighting for Markdown
  • Auto-completion for common markdown patterns
  • Multi-line editing with standard keyboard shortcuts
  • Real-time preview in the right column

​
Markdown quick reference

The editor supports GitHub Flavored Markdown:
# H1 Header
## H2 Header
### H3 Header

​
Example section templates

Each template comes with helpful placeholder content:
## Installation

Install my-project with npm

\`\`\`bash
  npm install my-project
  cd my-project
\`\`\`
5

Manage sections

As you build your README, you can:
  • Add more sections — Click any section in the available templates list
  • Remove sections — Click the delete (×) button on any added section
  • Reset sections — Click the reset icon to restore a section to its original template
  • Reset all — Click “Reset” at the top of the sections column to start over
// Section management (from SectionsColumn.js:119-125)
const onDeleteSection = (e, sectionSlug) => {
  e.stopPropagation()
  setSelectedSectionSlugs((prev) => prev.filter((s) => s !== sectionSlug))
  setSectionSlugs((prev) => [...prev, sectionSlug])
  setFocusedSectionSlug(null)
  localStorage.setItem('current-focused-slug', 'noEdit')
}
6

Use additional features

​
Dark mode

Toggle dark mode using the moon/sun icon in the navigation bar. Your preference is saved automatically.

​
Search sections

Use the search box above the available sections to quickly find specific templates:
// Search functionality (from SectionsColumn.js:181-187)
const getAutoCompleteResults = (searchQuery) => {
  const suggestedSlugs = sectionSlugs.filter((slug) => {
    return getTemplate(slug).name.toLowerCase().includes(searchQuery.toLowerCase())
  })
  
  return suggestedSlugs.length ? suggestedSlugs : [undefined]
}

​
Custom sections

Create your own sections by clicking “Add Custom Section” at the top of the sections list. Give it a name and start writing your own markdown content.

​
Auto-save

Your work is automatically saved to your browser’s local storage every second after you make changes:
// Auto-save implementation (from useLocalStorage.js:15-25)
const saveBackup = (templates) => {
  try {
    if (timer) {
      clearTimeout(timer)
    }
    
    setTimer(
      setTimeout(() => {
        localStorage.setItem('readme-backup', JSON.stringify(templates))
      }, 1000)
    )
  } catch (_) {
    console.error('Failed to create local backup')
  }
}
Auto-save only works in your current browser. If you clear your browser data or switch devices, your progress will be lost. Always download your README when you’re done!
7

Export your README

When you’re satisfied with your README, click the Download button in the navigation bar to save it as README.md.The download modal will appear with options:
  • Download — Save the file to your computer
  • Copy to clipboard — Copy the raw markdown (useful for quick edits)

​
Using your README

Once downloaded, add your README to your project:
# Move the downloaded file to your project directory
mv ~/Downloads/README.md /path/to/your/project/

# Add and commit to git
cd /path/to/your/project
git add README.md
git commit -m "Add comprehensive README documentation"
git push origin main
Your README will now appear on your GitHub repository homepage!
8

View raw markdown (optional)

Switch between Preview and Raw tabs in the right column to see:
  • Preview — Rendered markdown as it will appear on GitHub
  • Raw — Plain markdown text you can copy directly
This is useful for:
  • Copying specific sections to other documents
  • Debugging formatting issues
  • Sharing raw markdown in other platforms

​
Next steps

Now that you’ve created your first README, explore more features:

Master the editor

Learn about all editor features, keyboard shortcuts, and customization options

Explore section templates

Discover all 30+ available section templates and when to use each one

Customize your workflow

Set up dark mode, create custom sections, and optimize your editing experience

Use multiple languages

Switch between English, Chinese, Portuguese, and Turkish interfaces

​
Tips for great READMEs

The first thing visitors see should clearly explain what your project does and why it matters. Use the Title and Description section to create a compelling introduction.
Add screenshots, GIFs, or demo videos to show your project in action. Visual content helps users understand your project faster than text alone.
Provide clear, step-by-step installation instructions. Include prerequisites and common troubleshooting tips.
Include practical code examples that users can copy and run immediately. Show both basic and advanced use cases.
Return to Readme.so whenever you add new features or change how your project works. An outdated README can confuse potential users.

​
Troubleshooting

Make sure you’re using a modern browser with localStorage enabled. Check your browser’s settings to ensure localStorage isn’t blocked. Note that private/incognito mode may not persist data after closing the browser.
Try refreshing the page or clearing your browser cache. If the preview is still blank, check the browser console for any errors.
Ensure your browser allows file downloads from readme-so-community.vercel.app. Check if you have any download blocking extensions enabled.
Click the “Reset” button at the top of the sections column. This will remove all sections and restore the editor to its default state. Note: This cannot be undone!

​
Need help?

Join the community

Have questions or found a bug? Open an issue on GitHub or check existing discussions

Build docs developers (and LLMs) love

Get started for freeTalk to us