Customization - Readme.so

Readme.so offers several customization options to personalize your README creation experience. This guide covers all available customization features.

Dark Mode

Toggle between light and dark themes to match your preference or reduce eye strain.

Enabling Dark Mode

Locate the Theme Toggle

Find the sun/moon icon in the top navigation bar (on desktop) or in the tabs (on mobile)

Click to Toggle

Click the icon to switch between light and dark modes

Automatic Persistence

Your preference is saved to local storage and persists across sessions

How Dark Mode Works

The dark mode implementation uses localStorage to remember your preference:

// From Nav.js:66-77
<button
  onClick={() => setDarkMode(!darkMode)}
  aria-label="Color Mode"
  className="toggle-dark-mode"
>
  <Image
    alt={darkMode ? 'dark' : 'light'}
    src={darkMode ? '/toggle_sun.svg' : '/toggle_moon.svg'}
    width={40}
    height={40}
  />
</button>

Light Mode
Dark Mode

Clean, bright interface
Better for well-lit environments
Traditional documentation aesthetic
White background with dark text

Theme Persistence

Your theme choice is stored with these settings:

Storage key: color-theme
Values: 'light' or 'dark'
Scope: Persists across browser sessions
Location: Browser localStorage

The dark mode setting applies globally across all three columns: Sections, Editor, and Preview.

Custom Sections

Create completely custom README sections beyond the built-in templates.

Creating Custom Sections

Open Custom Section Dialog

Click the ”+ Add Custom Section” button in the Sections column

Enter Section Title

Type a descriptive name for your section (e.g., “Architecture”, “Performance”, “Security”)

Create Section

Click “Add Section” to create your custom section

Edit Content

The section appears in your selected sections list with a basic heading. Edit it in the Monaco editor to add your content.

Custom Section Features

Automatic Slug Generation

Your section title is converted to a URL-friendly slug (e.g., “My Section” becomes custom-my-section)

Full Markdown Support

Custom sections support all markdown features, just like built-in sections

Drag and Drop

Reorder custom sections alongside built-in sections

Persistent Storage

Custom sections are saved to localStorage and restored on your next visit

Custom Section Template

When you create a custom section, it starts with this basic template:

## Your Section Title

From there, you can add any content you need:

Example: Custom Architecture Section

## Architecture

Our application follows a microservices architecture with the following components:

### Frontend
- React SPA with TypeScript
- Redux for state management
- Styled with TailwindCSS

### Backend
- Node.js REST API
- PostgreSQL database
- Redis for caching

### Infrastructure
- Docker containers
- Kubernetes orchestration
- AWS cloud hosting

Managing Custom Sections

Custom sections can be managed just like built-in sections:

Action	Description
Edit	Click the section to edit its content in the Monaco editor
Reorder	Drag and drop to change position
Reset	Restores the section to its original heading
Delete	Removes the section from your README

Custom sections are identified by the custom- prefix in their slug. Avoid editing this prefix manually, as it may cause issues with section management.

Search and Filter

Quickly find sections in the library using the search filter.

Using Section Search

The search filter appears at the top of the available sections list in the Sections column.

Locate Search Box

Find the search input that says “Search for a section”

Type Keywords

Enter any part of the section name (e.g., “install”, “api”, “test”)

View Filtered Results

The section list updates in real-time to show only matching sections

Clear Search

Delete your search text to see all sections again

Search Behavior

The search filter uses case-insensitive substring matching:

// 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]
}

Successful Search
No Results

If matching sections are found, they appear alphabetically in the filtered list.Example: Searching for “git” returns:

Github Profile - About Me
Github Profile - Introduction
Github Profile - Links
Github Profile - Other
Github Profile - Skills

Search Tips

Use Partial Matches

You don’t need to type the complete section name. Searching for “env” will find “Environment Variables”.

Search by Topic

Search for topics like “test”, “install”, or “deploy” to find related sections.

Case Doesn't Matter

“API”, “api”, and “Api” all return the same results.

Clear Quickly

The search input has a clear button (X) for quickly resetting the filter.

Editor Customization

While the Monaco editor comes pre-configured, it includes several built-in features you can use:

Keyboard Shortcuts

The Monaco editor supports many VS Code keyboard shortcuts:

Shortcut	Action	Platform
`Ctrl/Cmd + F`	Find in editor	All
`Ctrl/Cmd + H`	Find and replace	All
`Alt + Up/Down`	Move line up/down	All
`Ctrl/Cmd + D`	Add selection to next find match	All
`Ctrl/Cmd + /`	Toggle line comment	All
`Alt + Click`	Add cursor at position	All
`Ctrl/Cmd + Z`	Undo	All
`Ctrl/Cmd + Shift + Z`	Redo	All

Editor Theme

The editor uses the vs-dark theme by default, which provides:

Dark background (#1E1E1E)
Syntax highlighting for markdown
Matching VS Code appearance
Optimized for extended editing sessions

The editor theme automatically switches based on your dark mode preference. When you toggle dark mode, both the preview and editor themes update accordingly.

Preview Customization

The preview column offers two viewing modes to suit different needs.

Preview Modes

Preview Mode
Raw Mode

Best for: Seeing exactly how your README will look on GitHubFeatures:

Full GitHub Flavored Markdown rendering
Live updates as you type
Proper styling for tables, code blocks, and images
Automatic external link handling

This mode uses the react-markdown library with remark-gfm plugin for accurate GitHub rendering.

Switching Preview Modes

On desktop, tabs appear at the top of the Preview column:

Click “Preview” to see the rendered markdown
Click “Raw” to see the markdown source

On mobile, preview modes are accessed through the main tab navigation.

Section Organization

Organize your README sections to match your project’s needs.

Reordering Sections

Find Selected Section

Look in the top portion of the Sections column where selected sections are listed

Drag Section

Click and hold any section, then drag it up or down

Drop in Position

Release to place the section in its new position

See Updated Preview

The preview column immediately reflects the new order

Best Practices for Section Order

Recommended Section Order

Title and Description - Always first
Badges - Right after the title for visibility
Logo/Screenshots - Visual introduction
Features - What makes your project unique
Installation - How to get started
Usage/Examples - How to use it
API Reference - Detailed documentation
Contributing - How others can help
License - Legal information
Authors/Acknowledgements - Credits

The drag-and-drop system uses @dnd-kit with collision detection and smooth animations for a polished reordering experience.

Local Storage Management

All your customizations are stored in browser localStorage for persistence.

What Gets Stored

Selected Sections

List of all sections you’ve added to your README

Section Content

All edits to both built-in and custom sections

Section Order

The current arrangement of your sections

Theme Preference

Your light/dark mode selection

Custom Sections

All custom sections you’ve created

Focused Section

Which section is currently being edited

Clearing Stored Data

To start completely fresh:

Click the Reset button in the Sections column header
Confirm the action in the dialog
All sections except “Title and Description” are removed
All customizations are cleared from localStorage

Resetting clears all your work and cannot be undone. Make sure to download your README first if you want to keep a copy.

Alternatively, you can manually clear localStorage through your browser’s developer tools:

Open DevTools (F12)
Go to Application > Storage > Local Storage
Select your domain
Delete the relevant keys or clear all storage

Accessibility Features

Readme.so includes several accessibility features:

Keyboard navigation for drag-and-drop operations
ARIA labels on all interactive elements
Focus indicators on buttons and inputs
Screen reader support through semantic HTML
High contrast in both light and dark modes

The Monaco editor also includes comprehensive accessibility features inherited from VS Code.

Get Started

User Guide

For Developers

Resources

​Dark Mode

​Enabling Dark Mode

​How Dark Mode Works

​Theme Persistence

​Custom Sections

​Creating Custom Sections

​Custom Section Features

Automatic Slug Generation

Full Markdown Support

Drag and Drop

Persistent Storage

​Custom Section Template

​Managing Custom Sections

​Search and Filter

​Using Section Search

​Search Behavior

​Search Tips

​Editor Customization

​Keyboard Shortcuts

​Editor Theme

​Preview Customization

​Preview Modes

​Switching Preview Modes

​Section Organization

​Reordering Sections

​Best Practices for Section Order

​Local Storage Management

​What Gets Stored

Selected Sections

Section Content

Section Order

Theme Preference

Custom Sections

Focused Section

​Clearing Stored Data

​Accessibility Features

Build docs developers (and LLMs) love

Dark Mode

Enabling Dark Mode

How Dark Mode Works

Theme Persistence

Custom Sections

Creating Custom Sections

Custom Section Features

Custom Section Template

Managing Custom Sections

Search and Filter

Using Section Search

Search Behavior

Search Tips

Editor Customization

Keyboard Shortcuts

Editor Theme

Preview Customization

Preview Modes

Switching Preview Modes

Section Organization

Reordering Sections

Best Practices for Section Order

Local Storage Management

What Gets Stored

Clearing Stored Data

Accessibility Features