GitAscii

Where cryptic terminals meet editorial broadsheet design.
Transform your GitHub profile into a live, encrypted telemetry deck and high-contrast ASCII artwork.

Launch Web App • How It Works • Quickstart • Creating Templates • Developer Scripts • Contributing

---

No setup needed to start: Design and preview your GitHub profile live in your browser at gitascii.com.

---

🎛️ Visual Drag-and-Drop Builder

Build your complete profile layout intuitively on a real-time reactive canvas. Move, resize, and configure telemetry decks, terminal metrics, and ASCII avatars directly in the browser.

📰 The Landing Platform

A classified broadsheet aesthetic engineered with brutalist minimalism, monospaced data streams, and high-contrast signal lime accents.

⚡ Live Generated SVG Output

What your GitHub profile actually renders: dynamic, high-density SVG output compiled on-the-fly at the edge with automatic dark/light theme switching.

---

How It Works

GitAscii uses a declarative layout file stored in your own GitHub profile repository. It connects your custom layout with edge-rendered dynamic data:

flowchart LR
    A["🎛️ GitAscii Web Editor<br/>(Design Layout)"] -->|"Download"| B["📄 gitascii.json<br/>(Config File)"]
    B -->|"Upload to Root"| C["🐙 GitHub Repo<br/>(username/username)"]
    C -->|"Live Query"| D["⚡ GitAscii Edge Server<br/>(Fetch Telemetry & Compile)"]
    D -->|"Dynamic SVG Stream"| E["🖼️ Profile README.md<br/>(Rendered in Browser)"]

    style A fill:#1f1f1f,stroke:#c5ff4a,stroke-width:1px,color:#ffffff
    style B fill:#060606,stroke:#252525,stroke-width:1px,color:#c5ff4a
    style C fill:#1f1f1f,stroke:#252525,stroke-width:1px,color:#ffffff
    style D fill:#1f1f1f,stroke:#c5ff4a,stroke-width:2px,color:#ffffff
    style E fill:#060606,stroke:#c5ff4a,stroke-width:1px,color:#c5ff4a

Loading

1. Design & Download Configuration

Compose your layout in the Visual Editor. When done, click Export to download your profile configuration file:

• Default profile: gitascii.json
• Custom profile slug: gitascii_[profile_slug].json

Note: Keep the exact filename. GitAscii strictly queries for this name in the root of your special repository.

2. Upload to your GitHub Profile Repository

Upload gitascii.json to the root of your special GitHub repository (username/username).

3. Embed into your Profile README.md

Paste the generated snippet into your README.md. It automatically adapts to the viewer's GitHub Dark or Light theme:

<img
  alt="GitAscii Profile"
  src="https://gitascii.com/api/user/yourusername?v=1740672000"
  width="100%"
/>

Tip (Cache Invalidation): GitHub caches external images through its Camo proxy. Whenever you update your gitascii.json, update the version parameter in your README links (e.g. using a current Unix timestamp like ?v=1740672000 or simply incrementing ?v=2) to force GitHub to fetch and render the new layout instantly.

---

Adding New Community Templates

Want to share a custom layout with the community? Adding a new template takes two simple steps:

1. Export the Template JSON in the Editor:
   Click the export template action in the sidebar. GitAscii automatically scrubs personal data (usernames, custom bio, avatars) while preserving the grid layout, widgets, and visual tokens.
2. Drop your JSON file into src/data/templates/:
   Place your file as src/data/templates/<template_name>.json and register it in src/data/templates/index.ts. Open a Pull Request and your template will be available to all GitAscii users!

---

Quickstart

Run your own instance of GitAscii locally:

# 1. Clone the repository
git clone https://github.com/Igorcbraz/GitAscii.git

# 2. Navigate to the project directory
cd GitAscii

# 3. Install dependencies
npm install

# 4. Start the development server
npm run dev

Open http://localhost:3000 in your browser.

---

Developer Scripts

All available scripts configured in package.json:

Command	Description
npm run dev	Starts the Next.js local development server on port 3000
npm run build	Compiles the production build and verifies type definitions
npm run start	Boots the compiled Next.js production server
npm run check	Comprehensive pipeline check: executes typecheck, lint, and build in sequence
npm run typecheck	Validates all TypeScript types across the codebase (tsc --noEmit)
npm run lint	Analyzes code for issues and stylistic discrepancies using ESLint
npm run lint:fix	Automatically fixes auto-fixable ESLint warnings and errors
npm run format	Formats the entire codebase using Prettier
npm run format:check	Verifies whether all files conform to Prettier formatting rules
npm run fix:all	Executes both lint:fix and format together for complete code cleanup
npm run test	Runs the full unit and integration test suite via Vitest
npm run test:e2e	Runs automated end-to-end browser tests via Playwright
npm run test:e2e:ui	Opens the Playwright interactive UI mode for visual debugging
npm run storybook	Launches the isolated UI widget and component workbench on port 6006
npm run build-storybook	Compiles the Storybook workbench into a static production bundle
npm run email:dev	Launches the React Email local preview server on port 3001
npm run docs	Launches the interactive documentation server locally via Mintlify
npm run prepare	Configures Git hooks (pre-commit, commit-msg) via Husky

---

Contributing

Contributions make the open-source community thrive. Follow this step-by-step workflow to contribute:

# 1. Fork the repository on GitHub, then clone your fork
git clone https://github.com/<your-username>/GitAscii.git
cd GitAscii

# 2. Install dependencies (initializes Husky hooks)
npm install

# 3. Create a descriptive feature/fix branch
git checkout -b feat/my-awesome-feature

# 4. Make your changes and verify code quality
npm run check
npm run test

# 5. Commit using Conventional Commits format (enforced by Commitlint)
git commit -m "feat(editor): add new ASCII matrix filter widget"

# 6. Push to your branch and open a Pull Request
git push origin feat/my-awesome-feature

Please review our CONTRIBUTING.md and CODE_OF_CONDUCT.md before submitting a pull request.

📈 Star History

📄 License

Distributed under the GNU General Public License v3.0 (GPLv3). See LICENSE for more information.

_{Engineered with design obsession by @Igorcbraz.}