ReadmeDesign Documentation
A technical overview of ReadmeDesign tooling architecture, client-side zero-retention privacy guarantees, GitHub Markdown parser constraints, and best practices.
1. Platform Architecture
ReadmeDesign is engineered as a zero-backend, client-side developer utility suite. Unlike traditional web applications that mandate user registration, authenticate GitHub OAuth tokens, and persist drafts in relational databases, ReadmeDesign runs entirely in the user's browser runtime.
This design decision was intentional: developers should never have to surrender third-party repository write permissions or store sensitive draft career documents on an external server simply to format Markdown.
How it works
Every tool on the platform — the README Generator, the Live Sandbox, and the Profile Analyzer — processes all user input exclusively in-browser using vanilla JavaScript. There is no application server, no API gateway, and no database sitting behind these tools. When you type your name, role, bio, or stack into the generator form, that data exists only in your browser's memory and is cleared the moment you navigate away or close the tab.
The only external network requests the site makes are:
- Google Fonts — loading IBM Plex Sans and IBM Plex Mono typefaces from fonts.googleapis.com
- Font Awesome — loading icon assets from Cloudflare CDN
- Google Analytics — anonymous page-view tracking (only if you accept analytics cookies)
- Google AdSense — advertisement serving (only if you accept advertising cookies)
- GitHub REST API — only used by the Analyzer when you enter a GitHub username to fetch public profile data. No credentials required.
Static hosting
The entire site is deployed as static HTML, CSS, and JavaScript files. There is no server-side rendering, no PHP, no Node.js process, and no database queries involved in serving any page. This means the site loads fast, scales trivially, and has no attack surface for server-side code injection.
2. Zero-Retention Privacy Model
Does ReadmeDesign store my README or GitHub credentials?
No. Absolutely not. ReadmeDesign never requires your GitHub password or Personal Access Token (PAT). All Markdown generation, parsing, real-time rendering, and scoring analysis happens client-side inside your browser sandbox.
When you edit templates or test profiles in our Live Sandbox:
- No network requests transmitting your Markdown content are sent to any application server.
- Content is serialized into browser memory or encoded client-side into the URL hash (
#data=...) using Base64 / URI encoding — so you can share links without sending data to a server. - No analytics trackers monitor the specific text or repository names you enter into our tools.
- Downloaded files (README.md, README.html, JSON configs) are built locally using the browser's native
BlobAPI andURL.createObjectURL()— no upload occurs.
Cookie consent model
On your first visit, a cookie consent banner appears. Analytics and advertising cookies are off by default — they only load after you click Accept. If you decline, Google Analytics and AdSense scripts are never injected. Your preference is stored for 365 days in a strictly necessary cookie named rmd_cookie_consent.
3. Live Sandbox Specification
The ReadmeDesign Sandbox provides a split-pane reactive Markdown editor and rendering preview modelled after GitHub's production CSS rendering engine. It implements:
- Syntax Sanitization: Emulates GitHub's HTML sanitizer, permitting safe tags (
<div align="center">,<details>,<summary>,<table>) while blocking unsafe script execution. - Theme Preview Toggles: Instant switching between GitHub light theme (
#F6F8FA) and dark theme (#0D1117) to verify asset contrast ratios. - Copy-to-Clipboard API: Native
navigator.clipboardintegration with visual toast feedback for rapid export. - Shareable Links: The Share button compresses your Markdown using LZ-string and writes it to the URL hash fragment (
window.location.hash). Under RFC 3986, hash fragments are never sent to the server — your content stays entirely in the browser. - Download Options: Export as a raw
.mdfile, a rendered.htmlfile, or copy to clipboard in one click.
Keyboard shortcuts
| Shortcut | Action |
|---|---|
Ctrl + S | Copy Markdown to clipboard |
Ctrl + Shift + D | Toggle dark / light preview theme |
Ctrl + Shift + F | Format / prettify Markdown source |
4. Generator Section Schema
The README Generator constructs standard GitHub-flavored Markdown through modular section composability. Each section is independently togglable — include or exclude any block without affecting the others. Output follows this order:
Supported widget URLs
The generator inserts the correct URL templates for the most popular README widgets. Replace your-username with your exact GitHub handle:
JSON config export
You can export your filled-in form as a .json configuration file. This lets you reload your settings later, share your profile structure with a teammate, or version-control your README config alongside your codebase.
5. Analyzer Heuristics & Scoring
The README Analyzer audits raw Markdown against our 10-dimension recruiter rubric. Paste your Markdown directly, or enter a GitHub username to fetch your profile automatically. All scoring runs client-side — your Markdown is never sent to a server.
Scoring dimensions
| Dimension | Points | What is measured |
|---|---|---|
| Project Architecture | 20 | Quality and depth of featured project descriptions |
| Impact Metrics | 20 | Measurable outcomes (users, performance gains, stars) |
| Technical Clarity | 15 | Stack is clearly named and honestly scoped |
| Profile Identity | 15 | Name, role, and one-line positioning present |
| Visual Readability | 10 | Appropriate headers, lists, and whitespace |
| Contact Completeness | 10 | At least two contact / social links present |
| Activity Signals | 5 | Stats cards or streak widgets present |
| Mobile Compatibility | 5 | No wide tables or oversized images detected |
| Freshness | 5 | "Currently working on" or recent activity present |
| Authenticity | 5 | No obvious placeholder text remaining |
For full technical rationale on dimension weighting, see the Scoring Methodology Whitepaper.
6. GitHub Markdown Rendering Quirks
GitHub's Markdown rendering engine (cmark-gfm) has several behaviours developers must account for when building profile READMEs:
1. Dark / Light Mode Image Toggling
GitHub does not support CSS media queries inside Markdown. To show different images in dark vs light mode, append GitHub's official hash fragments:
2. Center Alignment
GitHub permits <div align="center"> and <p align="center">, but inner Markdown headings (#) won't parse unless preceded by a blank line inside the tag.
3. Mobile Table Clipping
On the iOS and Android GitHub apps, tables with more than 4 columns clip horizontally. Keep project tables to 3–4 columns: Name, Description, Stack, Demo Link.
4. Stats Card Caching
GitHub aggressively caches README images. If an updated stats card still shows the old version, append ?v=2 to the image URL to bust the cache.
5. HTML Inside Table Cells
GitHub strips most HTML tags inside pipe-table cells. Use plain Markdown syntax inside tables, or switch to a full <table> HTML block for complex layouts.
6. Emoji Shortcodes
GitHub supports Gemoji shortcodes like :rocket: and :zap: natively. For maximum compatibility across all GitHub clients and API consumers, prefer Unicode emoji directly (?? ? ??).
7. Frequently Asked Questions
Q: How do I activate my GitHub Profile README?
Create a new public repository with the exact same name as your GitHub username (e.g. if your username is johndoe, the repo is named johndoe). Add a README.md to the root of the default branch. GitHub will automatically render it at the top of your public profile page.
Q: My stats card shows an error or blank image. How do I fix it?
The most common cause is a wrong or placeholder username — the URL is case-sensitive. Check that you replaced your-username with your exact GitHub handle. Also confirm that your public contribution settings are enabled: go to Settings ? Public Profile and ensure "Make profile private" is unchecked. If the card still fails, the free hosting instance may be rate-limited — try again in a few minutes.
Q: Can I use these templates for a GitHub organisation profile?
Yes. Create a public repository named .github inside your organisation, then add a profile/README.md file inside it. GitHub renders it on your organisation's public page. Most templates work as-is with minor wording adjustments.
Q: How do I keep my README updated automatically?
Use GitHub Actions workflows to auto-update sections on a schedule — fetch blog posts via RSS, update Wakatime coding hours, or pull in your latest release tag. See our guide: Auto-Update Your GitHub Profile README with GitHub Actions.
Q: Are all templates compatible with the GitHub mobile app?
Yes. All 9 templates are tested across desktop viewports and the official GitHub iOS and Android clients to prevent broken layouts, badge overflow, or unreadable table margins. Always verify on a real mobile device after publishing.