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.
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 either into browser memory or encoded client-side into the URL hash (e.g.
#data=...) using native Base64 / URI encoding so you can bookmark or share links. - No analytics trackers monitor the specific text or repository names you enter into our tools.
3. Live Sandbox Specification
The ReadmeDesign Sandbox provides a split-pane reactive Markdown editor and rendering preview modeled 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 escaping unsafe script execution. - Theme Preview Toggles: Supports instant switching between GitHub light theme (
#F6F8FA) and dark theme (#0D1117) to verify asset contrast. - Copy-to-Clipboard API: Native
navigator.clipboardintegration with visual toast feedback for rapid export.
4. Generator Section Schema
The README Generator constructs standard GitHub-flavored Markdown through modular section composability:
5. Analyzer Heuristics & Scoring
The README Analyzer audits raw Markdown against our 10-dimension recruiter rubric. For complete technical rationale on weighting project architecture (20 pts) and impact metrics (20 pts) over cosmetic widgets, review our dedicated Scoring Methodology Whitepaper.
6. GitHub Markdown Rendering Quirks
GitHub's Markdown rendering engine (cmark-gfm) includes several idiosyncratic behaviors developers must account for:
1. Dark Mode / Light Mode Image Toggles
GitHub does not support CSS media queries inside Markdown images. To display distinct banner assets for dark and light modes, append the official GitHub hash fragments to your image URLs:
2. Center Alignment Syntax
Markdown lacks native text alignment tags. GitHub permits wrapping elements in raw HTML <p align="center"> or <div align="center">, but inner Markdown (such as headings #) will not parse unless preceded by a blank line.
3. Mobile GitHub App Table Scrolling
On the iOS and Android GitHub native apps, Markdown tables with more than 4 columns cause horizontal clipping. We recommend limiting project tables to 3 or 4 columns (Project Name, Problem Context, Stack, Demo Link).
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. github.com/yourname/yourname). Add a README.md file to the root of the default branch. GitHub will automatically render it at the top of your public profile.
Q: Are all templates compatible with GitHub's mobile app?
Yes. All 9 templates in our gallery are tested across desktop viewports and the official GitHub mobile client to prevent broken layouts, badge overflow, or unreadable table margins.