gitora-md — Next.js Tool Template

SHA-256: 309115235d78aba65115f7bc82f1fddcb3f7c142efd073fd2a9855cfb3f7996b

2026-10-14T21:02:24.151Z

# Gitora.md

**A visual, local-first GitHub Profile README builder.**

[Live Demo](https://gitora-md.vercel.app) · [Browse Templates](https://gitora-md.vercel.app/templates) · [Open Builder](https://gitora-md.vercel.app/builder) · [Contributing](CONTRIBUTING.md) · [Report Bug](https://github.com/manujayagunathilaka/gitora-md/issues) · [Request Feature](https://github.com/manujayagunathilaka/gitora-md/issues)

Gitora.md allows software engineers, open-source maintainers, educators, and students to build clean, accessible, and GitHub-compatible Profile READMEs with curated templates, technology icons, layout reordering controls, and live GitHub-style preview.

[![CI](https://github.com/manujayagunathilaka/gitora-md/actions/workflows/ci.yml/badge.svg)](https://github.com/manujayagunathilaka/gitora-md/actions/workflows/ci.yml)
[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-v0.1.0-blue.svg)](CHANGELOG.md)
[![Next.js](https://img.shields.io/badge/Next.js-16.2.10-black.svg?logo=nextdotjs)](https://nextjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue.svg?logo=typescript)](https://www.typescriptlang.org/)
[![pnpm](https://img.shields.io/badge/pnpm-11.15.1-orange.svg?logo=pnpm)](https://pnpm.io/)
[![Privacy](https://img.shields.io/badge/Privacy-Local--First-success.svg)](#privacy-and-local-first-behavior)

---

## Product Preview

![Gitora.md README builder showing profile customization and live preview](docs/assets/gitora-builder-dark.png)

*Gitora.md 7-step builder pipeline with live GitHub-style Markdown preview.*

<details>
<summary><strong>View Additional Interface Screenshots</strong></summary>

### Landing Page & Gallery
![Gitora.md Landing Page](docs/assets/gitora-home-dark.png)

### README Templates Gallery
![Gitora.md 10 Curated README Templates Gallery](docs/assets/gitora-templates-dark.png)

### GitHub-Style Preview Step
![Gitora.md Live Preview and One-Click Export](docs/assets/gitora-preview-dark.png)

### Mobile Responsive Interface
![Gitora.md Mobile Viewport Support](docs/assets/gitora-mobile.png)

</details>

---

## Key Features

- **7-Step Guided Builder**: Progressive, structured pipeline (`Template` → `Profile` → `Tech Stack` → `Projects` → `Social` → `Layout` → `Preview & Export`).
- **10 Curated README Templates**: Distinct, GitHub-compatible layouts categorized into `Minimal`, `Professional`, `Portfolio`, and `Community`.
- **Multi-Provider Technology Icon System**: 5 presentation modes (`text`, `code-pills`, `gitora-icons`, `skill-icons`, `shields`) with URL-length chunking, theme toggles, and zero-network default fallback.
- **Technology Selector**: Curated catalog of 34 technologies with 5-tier ranked search (`exact` → `prefix` → `alias` → `substring`), category filtering, and provider presentation controls.
- **GitHub-Style Live Preview**: Sanitized Markdown rendering engine powered by `react-markdown`, `remark-gfm`, `rehype-raw`, and `rehype-sanitize`.
- **Accessible Layout Customization**: Keyboard-operable section visibility toggles and `Move Up` / `Move Down` reordering controls with `aria-live` screen-reader announcements.
- **One-Click Export**: Copy generated Markdown directly to your clipboard or download as a UTF-8 `README.md` file.
- **Local Draft Persistence**: Debounced `localStorage` auto-saving, versioned migration (v1 → v2), corrupted-draft recovery, and confirmation reset modal.
- **External Asset Disclosure**: Transparent notifications when remote image providers (Gitora SVGs, Skill Icons, Shields.io) are enabled, including estimated request counts and 1-click fallback to code-pills.

---

## Template Inventory

Gitora.md includes ten distinct, GitHub-compatible README templates:

| Template ID | Name | Category | Primary Audience & Layout Highlights | Supported Presentations |
|---|---|---|---|---|
| `minimal` | Minimal | **Minimal** | Text-focused, clean headings, simple bullet points, no emojis. | `text`, `code-pills` |
| `compact` | Compact | **Minimal** | Ultra-concise single-screen profile layout. | `text`, `code-pills` |
| `modern` | Modern | **Minimal** | Blockquote headline, tech pills, and structured project cards. | `text`, `code-pills`, `shields` |
| `professional` | Professional | **Professional** | Recruiter-friendly formal tone with categorized tech stack. | `text`, `code-pills`, `shields` |
| `technical` | Technical | **Professional** | Terminal prompt hero, categorized tech stack, systems architecture. | `text`, `code-pills`, `gitora-icons`, `skill-icons`, `shields` |
| `centered` | Centered | **Portfolio** | Centered hero header with balanced visual layout. | `text`, `code-pills`, `gitora-icons`, `skill-icons`, `shields` |
| `portfolio` | Portfolio | **Portfolio** | Showcase-first layout highlighting top projects & demo links. | `text`, `code-pills`, `gitora-icons`, `skill-icons` |
| `creative` | Creative | **Portfolio** | Expressive layout for frontend engineers and UI coders. | `text`, `code-pills`, `gitora-icons`, `skill-icons`, `shields` |
| `open-source` | Open Source | **Community** | Repository-first hierarchy for maintainers & contributors. | `text`, `code-pills`, `shields` |
| `community` | Community | **Community** | Developer advocates, educators, and community mentors. | `text`, `code-pills`, `skill-icons`, `shields` |

---

## Technology Presentation Modes

1. **Text (`text`)**: Pure Markdown text lists with zero remote images or badges.
2. **Code Pills (`code-pills`)**: Network-free Markdown inline code blocks (`\`React\``).
3. **Gitora Icons (`gitora-icons`)**: Clean vector SVGs hosted on Gitora CDN (`public/assets/icons/v1/`).
4. **Skill Icons (`skill-icons`)**: Consolidated tech stack grids powered by `skillicons.dev`.
5. **Shields Badges (`shields`)**: Flat badges powered by `img.shields.io`.

---

## Privacy and Local-First Behavior

- **Browser Storage Only**: Profile form inputs are stored locally in your browser's `localStorage`.
- **Zero Profile Tracking**: Profile form data is never transmitted to Gitora.md servers or external databases.
- **Network-Free Default**: The default presentation mode (`"code-pills"`) makes 0 network requests.
- **Optional Third-Party Asset Loading**: If you select optional image providers (`gitora-icons`, `skill-icons`, `shields`), your browser fetches public icon assets from allowlisted HTTPS hosts (`gitora-md.vercel.app`, `skillicons.dev`, `img.shields.io`). Profile data is never sent in those requests.

---

## Tech Stack

- **Framework**: Next.js 16 (App Router)
- **Language**: TypeScript (Strict Mode)
- **Styling**: Tailwind CSS v4 & Radix UI primitives
- **Form & Validation**: React Hook Form & Zod
- **Markdown & Sanitization**: `react-markdown`, `remark-gfm`, `rehype-raw`, `rehype-sanitize`, `github-markdown-css`
- **Testing**: Vitest, React Testing Library, Playwright E2E
- **Package Manager**: `pnpm`

---

## Getting Started

### Prerequisites

- **Node.js**: use the exact version declared in `.nvmrc` (Node.js `24`)
- **pnpm**: use the exact version declared by `packageManager` in `package.json` (`[email protected]`)

### Local Setup

```bash
# 1. Clone the repository
git clone https://github.com/manujayagunathilaka/gitora-md.git
cd gitora-md

# 2. Install dependencies
pnpm install

# 3. Copy environment configuration template
cp .env.example .env.local

# 4. Start development server
pnpm dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser.

---

## Environment Variables

Documented in `.env.example`:

| Variable Name | Required | Scope | Purpose & Default |
|---|---|---|---|
| `APP_URL` | Optional | Server-Only | Application base origin (Defaults to `https://gitora-md.vercel.app`). |
| `NEXT_PUBLIC_GITORA_ASSET_BASE_URL` | Optional | Public | HTTPS origin hosting `/assets/icons/v1/` SVGs. |
| `NEXT_PUBLIC_ENABLE_GITORA_ICONS` | Optional | Public | Feature flag enabling Gitora-hosted vector icons (Defaults to `false`). |

---

## Available Scripts

```bash
pnpm dev        # Start development server
pnpm build      # Build Next.js production bundle (SSG prerendering)
pnpm start      # Start local production server
pnpm lint       # Run ESLint check
pnpm typecheck  # Run TypeScript strict typecheck
pnpm test       # Run Vitest unit & component tests
pnpm test:e2e   # Run Playwright end-to-end tests
```

---

## Automated Verification & Quality Gates

The repository uses automated linting, strict typechecking, unit and component tests, production builds, and Playwright end-to-end verification:

```bash
pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm test:e2e
```

---

## Contributing

We welcome open-source contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) before submitting pull requests.

---

## Security Policy

Security vulnerabilities should be reported privately to:
**[email protected]**

See [SECURITY.md](SECURITY.md) for details.

---

## License

This project is licensed under the [MIT License](LICENSE).

See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for open-source asset disclosures and trademark acknowledgments.