5137033b19
- Added extensive project documentation covering all features - Beautiful visual design with badges, shields, and banners - Included architecture diagrams and style system deep-dive - Added contribution guidelines and philosophy section - Wove in themes of collective benefit, commons, and mutual aid throughout - Celebrated open-source as a model of voluntary cooperation
490 lines
20 KiB
Markdown
490 lines
20 KiB
Markdown
<div align="center">
|
||
|
||
<!-- Animated Banner -->
|
||
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:6366f1,50:8b5cf6,100:a855f7&height=200§ion=header&text=TypoGenie&fontSize=70&fontColor=ffffff&animation=fadeIn&fontAlignY=35" alt="TypoGenie Banner" />
|
||
|
||
<br/><br/>
|
||
|
||
<!-- Beautiful Tagline -->
|
||
<blockquote>
|
||
<i>"From each according to their Markdown, to each according to their Word documents."</i>
|
||
</blockquote>
|
||
|
||
<br/>
|
||
|
||
<!-- Badges -->
|
||
<p>
|
||
<img src="https://img.shields.io/badge/React-19-61DAFB?style=for-the-badge&logo=react&logoColor=white" alt="React" />
|
||
<img src="https://img.shields.io/badge/TypeScript-5.8-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
|
||
<img src="https://img.shields.io/badge/Vite-6-646CFF?style=for-the-badge&logo=vite&logoColor=white" alt="Vite" />
|
||
<img src="https://img.shields.io/badge/Tailwind-3-06B6D4?style=for-the-badge&logo=tailwindcss&logoColor=white" alt="Tailwind" />
|
||
</p>
|
||
|
||
<p>
|
||
<img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License" />
|
||
<img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square" alt="PRs Welcome" />
|
||
<img src="https://img.shields.io/badge/community-owned-ff69b4?style=flat-square" alt="Community" />
|
||
</p>
|
||
|
||
<br/>
|
||
|
||
<!-- Quick Links -->
|
||
<p>
|
||
<a href="#-features">✨ Features</a> •
|
||
<a href="#-demo">🎨 Demo</a> •
|
||
<a href="#-quick-start">🚀 Quick Start</a> •
|
||
<a href="#-documentation">📚 Docs</a> •
|
||
<a href="#-contributing">🤝 Contribute</a>
|
||
</p>
|
||
|
||
</div>
|
||
|
||
---
|
||
|
||
<br/>
|
||
|
||
## 📖 Manifesto
|
||
|
||
> **TypoGenie** is a free, open-source typesetting engine that democratizes beautiful document creation. No corporate subscriptions. No proprietary lock-in. No gatekeeping. Just you, your words, and 40+ professionally crafted styles ready to transform your Markdown into stunning Microsoft Word documents.
|
||
|
||
In a world where document formatting tools are increasingly locked behind paywalls and cloud dependencies, **TypoGenie stands as a testament to collective utility** — software built for the community, by the community, existing solely to serve the common good of anyone who needs to make their words look beautiful.
|
||
|
||
<br/>
|
||
|
||
<div align="center">
|
||
|
||
| 🌟 **Free Forever** | 🔒 **Privacy First** | 🎨 **40+ Styles** | 🤝 **Open Source** |
|
||
|:---:|:---:|:---:|:---:|
|
||
| No fees, no trials, no catches | All processing happens locally on your machine | From minimalist to ornate, academic to artistic | MIT licensed — use it, fork it, improve it together |
|
||
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
### 🎯 Core Capabilities
|
||
|
||
- **📄 Universal Markdown Support** — Drop in any `.md`, `.txt`, or `.markdown` file
|
||
- **🎨 40+ Typography Styles** — Curated across 8 aesthetic categories
|
||
- **📐 Multiple Paper Sizes** — A4 and Letter formats supported
|
||
- **💾 Local Processing** — Your documents never leave your machine
|
||
- **📥 One-Click Export** — Clean `.docx` files ready for Microsoft Word
|
||
|
||
### 🏛️ Style Categories
|
||
|
||
Each style is a labor of love, crafted with attention to typographic detail:
|
||
|
||
| Category | Description | Example Styles |
|
||
|----------|-------------|----------------|
|
||
| **🤍 Minimalist** | Clean, breathing room, Swiss precision | Swiss Grid, Brutalist, Monospace |
|
||
| **🏢 Corporate** | Professional, authoritative, trustworthy | Executive, Financial, Legal |
|
||
| **📰 Editorial** | Magazine-quality, high-contrast, readable | Glossy, Newsprint, Feature |
|
||
| **💻 Tech** | Startup aesthetic, modern, sleek | SaaS, Y Combinator, Terminal |
|
||
| **🎭 Creative** | Expressive, artistic, bold | Poster, Zine, Experimental |
|
||
| **📜 Vintage** | Timeless elegance, historical charm | Victorian, Art Deco, Baroque |
|
||
| **🌿 Lifestyle** | Warm, inviting, personal | Cookbook, Travel, Botanical |
|
||
| **⚙️ Industrial** | Technical, mechanical, utilitarian | Blueprint, Shipping, Workshop |
|
||
|
||
### 🔤 Typography Features
|
||
|
||
Every style includes meticulously configured:
|
||
|
||
- ✅ **Google Fonts Integration** — Beautiful web fonts that translate to Word
|
||
- ✅ **Hierarchical Headings** — H1-H6 with distinct visual weight
|
||
- ✅ **Body Text Optimization** — Optimal line height, spacing, and readability
|
||
- ✅ **List Formatting** — Bulleted and numbered lists that work
|
||
- ✅ **Blockquote Styling** — Pull quotes with accent colors
|
||
- ✅ **Table Support** — Data tables with proper borders and alignment
|
||
- ✅ **Bold & Italic** — Emphasis that carries through to the final document
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 🎨 Demo
|
||
|
||
<div align="center">
|
||
|
||
### The Transformation
|
||
|
||
```
|
||
┌─────────────────────────────────────┐ ┌─────────────────────────────────────┐
|
||
│ YOUR INPUT │ │ TYPOGENIE OUTPUT │
|
||
│ ─────────── │ ⚡ │ ──────────────── │
|
||
│ │ → │ │
|
||
│ # My Document │ │ ┌─────────────────────────────┐ │
|
||
│ │ │ │ My Document │ │
|
||
│ Some **bold** text here. │ │ │ (Beautifully │ │
|
||
│ │ │ │ Formatted) │ │
|
||
│ - Point one │ │ └─────────────────────────────┘ │
|
||
│ - Point two │ │ │
|
||
│ │ │ Some bold text here. │
|
||
│ > A wise quote │ │ │
|
||
│ │ │ • Point one │
|
||
│ │ │ • Point two │
|
||
│ │ │ │
|
||
│ │ │ ┌─────────────────────────────┐ │
|
||
│ │ │ │ "A wise quote" │ │
|
||
│ │ │ └─────────────────────────────┘ │
|
||
└─────────────────────────────────────┘ └─────────────────────────────────────┘
|
||
```
|
||
|
||
</div>
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 🚀 Quick Start
|
||
|
||
### Prerequisites
|
||
|
||
- **Node.js** 18+ (we recommend the latest LTS)
|
||
- A modern web browser
|
||
- Your favorite text editor
|
||
|
||
### Installation
|
||
|
||
```bash
|
||
# 1. Clone the collective's work
|
||
git clone https://git.lashman.live/lashman/typogenie.git
|
||
|
||
# 2. Enter the commons
|
||
cd typogenie
|
||
|
||
# 3. Gather dependencies (mutual aid from npm)
|
||
npm install
|
||
|
||
# 4. Start the local development server
|
||
npm run dev
|
||
```
|
||
|
||
Your browser will open to `http://localhost:3000` — and you're ready to create!
|
||
|
||
### Usage
|
||
|
||
1. **📤 Upload** — Drag and drop your Markdown file (or click to browse)
|
||
2. **🎨 Select Style** — Browse the gallery and click any style for live preview
|
||
3. **📐 Choose Paper Size** — A4 or Letter, depending on your needs
|
||
4. **✨ Generate** — Watch the magic happen (with a satisfying loading animation)
|
||
5. **📥 Download** — Grab your `.docx` file, ready for Word
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 📚 Documentation
|
||
|
||
### Architecture Overview
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ TYPOGENIE ARCHITECTURE │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ UPLOAD │───→│ CONFIG │───→│ PREVIEW │ │
|
||
│ │ (File) │ │ (Style) │ │ (Export) │ │
|
||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||
│ │ STATE MACHINE │ │
|
||
│ │ • UPLOAD → CONFIG → GENERATING → PREVIEW → (reset) │ │
|
||
│ └────────────────────────────────────────────────────────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||
│ │ PROCESSING PIPELINE │ │
|
||
│ │ Markdown → marked parser → HTML → docx library → .docx │ │
|
||
│ └────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### Style System Deep Dive
|
||
|
||
Each style in TypoGenie is defined by a comprehensive configuration object:
|
||
|
||
```typescript
|
||
interface StyleOption {
|
||
id: string; // Unique identifier
|
||
name: string; // Display name
|
||
category: string; // Grouping category
|
||
description: string; // What this style evokes
|
||
vibe: string; // Emotional keywords
|
||
googleFontsImport: string; // Font resources
|
||
|
||
wordConfig: {
|
||
heading1: DocxStyleConfig; // H1 formatting rules
|
||
heading2: DocxStyleConfig; // H2 formatting rules
|
||
body: DocxStyleConfig; // Body text rules
|
||
accentColor: string; // Theme accent color
|
||
};
|
||
|
||
previewCss: string; // Web preview styling
|
||
}
|
||
```
|
||
|
||
**The Dual Rendering Challenge:**
|
||
|
||
TypoGenie maintains two parallel rendering paths for every style:
|
||
1. **Web Preview** — CSS-based preview in the browser
|
||
2. **DOCX Export** — Programmatic document generation via the `docx` library
|
||
|
||
This ensures WYSIWYG fidelity: what you see in the preview is what you get in Word.
|
||
|
||
### Adding Custom Styles
|
||
|
||
Want to contribute a new style to the collective? Here's how:
|
||
|
||
1. **Choose a Category** — Find the appropriate file in `/styles/`
|
||
2. **Define Your Style** — Create a complete `StyleOption` object:
|
||
|
||
```typescript
|
||
{
|
||
id: 'my-custom-style',
|
||
name: 'My Style',
|
||
category: 'Creative',
|
||
description: 'A brief description of the aesthetic',
|
||
vibe: 'Keywords that capture the feeling',
|
||
googleFontsImport: 'https://fonts.googleapis.com/css2?family=YourFont&display=swap',
|
||
wordConfig: {
|
||
heading1: {
|
||
font: 'Your Font',
|
||
size: 24,
|
||
color: '1a1a1a',
|
||
bold: true,
|
||
// ... more properties
|
||
},
|
||
heading2: { /* ... */ },
|
||
body: { /* ... */ },
|
||
accentColor: '6366f1'
|
||
},
|
||
previewCss: `
|
||
h1 { font-family: 'Your Font'; font-size: 24pt; }
|
||
/* ... match wordConfig exactly */
|
||
`
|
||
}
|
||
```
|
||
|
||
3. **Export It** — Add to the category's export array
|
||
4. **Test Both Paths** — Verify preview looks right AND Word export works
|
||
5. **Share With All** — Submit a PR so everyone benefits!
|
||
|
||
### Configuration Options
|
||
|
||
#### Paper Sizes
|
||
|
||
| Size | Dimensions | Best For |
|
||
|------|------------|----------|
|
||
| **A4** | 210mm × 297mm | International use, academic papers |
|
||
| **Letter** | 8.5in × 11in | US/Canada, business documents |
|
||
|
||
#### Margins
|
||
|
||
All documents use generous, readable margins:
|
||
- **Top/Bottom:** 1 inch (25.4mm)
|
||
- **Left/Right:** 1.2 inches (30.5mm)
|
||
|
||
This follows established typographic best practices for comfortable reading.
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 🛠️ Development
|
||
|
||
### Available Scripts
|
||
|
||
```bash
|
||
# Development server with hot reload
|
||
npm run dev
|
||
|
||
# Production build (outputs to dist/)
|
||
npm run build
|
||
|
||
# Preview production build locally
|
||
npm run preview
|
||
```
|
||
|
||
### Project Structure
|
||
|
||
```
|
||
typogenie/
|
||
├── 📁 components/ # React components
|
||
│ ├── FileUpload.tsx # Drag-and-drop upload zone
|
||
│ ├── StyleSelector.tsx # Style gallery with live preview
|
||
│ ├── Preview.tsx # Final preview & DOCX export
|
||
│ └── StylePreviewModal.tsx # (Optional) Modal preview
|
||
├── 📁 styles/ # Typography style definitions
|
||
│ ├── index.ts # Aggregates all categories
|
||
│ ├── minimalist.ts # 11 clean styles
|
||
│ ├── corporate.ts # 13 professional styles
|
||
│ ├── editorial.ts # Magazine aesthetics
|
||
│ ├── tech.ts # Modern tech vibes
|
||
│ ├── creative.ts # Artistic expressions
|
||
│ ├── vintage.ts # Historical elegance
|
||
│ ├── lifestyle.ts # Warm & personal
|
||
│ ├── industrial.ts # Technical & mechanical
|
||
│ ├── academic.ts # Scholarly formats
|
||
│ ├── volume1.ts # Legacy collection
|
||
│ └── volume2.ts # Extended collection
|
||
├── 📁 services/ # (Currently empty - local processing!)
|
||
├── 📄 App.tsx # Main application with state machine
|
||
├── 📄 types.ts # TypeScript interfaces
|
||
├── 📄 constants.ts # Configuration exports
|
||
├── 📄 index.html # Entry HTML with Tailwind CDN
|
||
└── 📄 vite.config.ts # Build configuration
|
||
```
|
||
|
||
### Technology Stack
|
||
|
||
| Layer | Technology | Purpose |
|
||
|-------|------------|---------|
|
||
| **Framework** | React 19.2.4 | UI components & state management |
|
||
| **Language** | TypeScript 5.8.2 | Type safety & developer experience |
|
||
| **Build Tool** | Vite 6.2.0 | Fast development & optimized builds |
|
||
| **Styling** | Tailwind CSS | Utility-first CSS |
|
||
| **Icons** | Lucide React | Beautiful, consistent iconography |
|
||
| **Markdown** | marked 12.0.0 | Local Markdown parsing |
|
||
| **Documents** | docx 8.5.0 | Client-side DOCX generation |
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 🤝 Contributing
|
||
|
||
TypoGenie is a **commons** — it belongs to everyone who uses it and improves it. We welcome contributions of all kinds:
|
||
|
||
### Ways to Contribute
|
||
|
||
- 🎨 **New Styles** — Design and share new typography styles
|
||
- 🐛 **Bug Reports** — Found something broken? Let us know!
|
||
- 💡 **Feature Ideas** — Have a suggestion? Open a discussion
|
||
- 📖 **Documentation** — Help us explain things better
|
||
- 🔧 **Code Improvements** — Refactors, optimizations, fixes
|
||
- 🌍 **Translations** — Help make TypoGenie accessible globally
|
||
|
||
### Contribution Guidelines
|
||
|
||
1. **Fork the repository**
|
||
2. **Create a feature branch**: `git checkout -b feature/amazing-thing`
|
||
3. **Make your changes** with clear, descriptive commits
|
||
4. **Test thoroughly** — preview AND Word export
|
||
5. **Submit a Pull Request** with a detailed description
|
||
|
||
### Code of Conduct
|
||
|
||
- Be respectful and constructive
|
||
- Assume good intentions
|
||
- Help newcomers learn and grow
|
||
- Focus on what's best for the community
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 📜 Philosophy & License
|
||
|
||
### Why Free? Why Open?
|
||
|
||
TypoGenie exists because we believe:
|
||
|
||
> **Access to beautiful tools for self-expression should not depend on one's ability to pay.**
|
||
|
||
In an era of increasingly proprietary, subscription-based software, TypoGenie is an offering to the digital commons — a tool that exists purely to serve those who need it, without extracting value, without surveillance, without artificial limitations.
|
||
|
||
### MIT License
|
||
|
||
```
|
||
MIT License
|
||
|
||
Copyright (c) 2026 TypoGenie Contributors
|
||
|
||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||
of this software and associated documentation files (the "Software"), to deal
|
||
in the Software without restriction, including without limitation the rights
|
||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||
copies of the Software, and to permit persons to whom the Software is
|
||
furnished to do so, subject to the following conditions:
|
||
|
||
The above copyright notice and this permission notice shall be included in all
|
||
copies or substantial portions of the Software.
|
||
|
||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||
SOFTWARE.
|
||
```
|
||
|
||
**tl;dr:** Do whatever you want with this code. Just keep the license notice. Share it. Modify it. Use it for whatever purpose serves your community. No attribution required beyond preserving the license, though we always appreciate a shout-out!
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
## 🙏 Acknowledgments
|
||
|
||
TypoGenie stands on the shoulders of giants — the countless open-source contributors who built the libraries, tools, and standards that make this project possible:
|
||
|
||
- **The React Team** — For the component model that powers our UI
|
||
- **The marked contributors** — For battle-tested Markdown parsing
|
||
- **The docx maintainers** — For making client-side Word generation possible
|
||
- **Google Fonts** — For democratizing access to beautiful typography
|
||
- **Tailwind CSS** — For the utility-first approach that speeds development
|
||
- **Vite** — For the build tooling that makes development a joy
|
||
- **The broader open-source community** — For proving that collective, voluntary cooperation can create tools that rival (and exceed) proprietary alternatives
|
||
|
||
**And to you, the user** — for choosing tools that respect your freedom.
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
<div align="center">
|
||
|
||
## 💬 Connect
|
||
|
||
<p>
|
||
<a href="https://git.lashman.live/lashman/typogenie">
|
||
<img src="https://img.shields.io/badge/Gitea-609926?style=for-the-badge&logo=gitea&logoColor=white" alt="Gitea" />
|
||
</a>
|
||
</p>
|
||
|
||
<br/>
|
||
|
||
### ☕ Support the Commons
|
||
|
||
If TypoGenie brings value to your life, consider:
|
||
|
||
- ⭐ **Starring the repository** — Helps others discover it
|
||
- 🗣️ **Spreading the word** — Tell friends and colleagues
|
||
- 🔧 **Contributing code** — Improve it for everyone
|
||
- 💝 **Supporting open-source** — Donate to the projects TypoGenie depends on
|
||
|
||
<br/>
|
||
|
||
---
|
||
|
||
<p>
|
||
<i>"The master's tools will never dismantle the master's house. But they might help you format a really nice document while we build something better together."</i>
|
||
</p>
|
||
|
||
<p>
|
||
<strong>Made with ❤️ for the many, not the few.</strong>
|
||
</p>
|
||
|
||
<br/>
|
||
|
||
<img src="https://capsule-render.vercel.app/api?type=waving&color=0:a855f7,50:8b5cf6,100:6366f1&height=100§ion=footer" alt="Footer" />
|
||
|
||
</div>
|