Igorcbraz/GitAscii

GitAscii

Where cryptic terminals meet editorial broadsheet design.
Design a GitHub profile in your browser and publish self-contained ASCII and widget SVGs to your own repository.

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

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

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.

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

What your GitHub profile actually renders: self-contained dark and light SVG files generated when you publish and refreshed by a GitHub Action. The README uses a <picture> element to select the viewer's theme.

GitAscii v2 publishes self-contained SVG files to a dedicated gitascii branch in your GitHub profile repository (username/username). A GitHub Action refreshes them from current GitHub data. The normal README embed loads those files from GitHub:

flowchart LR
    A["🎛️ GitAscii Web Editor<br/>(Design Layout)"] -->|"Publish"| B["🌿 gitascii branch<br/>(Config + SVGs)"]
    B -->|"GitHub Action refresh"| C["📄 profiles/slug/*.svg"]
    C -->|"raw.githubusercontent.com"| E["🖼️ Profile README.md<br/>(Rendered by GitHub)"]

    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 E fill:#060606,stroke:#c5ff4a,stroke-width:1px,color:#c5ff4a

Compose your layout in the Visual Editor. Sign in, authorize the GitHub App for your profile repository, and use Publish to GitHub. GitAscii creates the repository if needed and creates or updates:

• the dedicated gitascii branch;
• gitascii.json for the default profile and gitascii_[slug].json for additional profiles;
• dark and light SVG files under profiles/[slug]/;
• .github/workflows/gitascii.yml on the default branch.

The app renders an initial dark/light pair at publication. The workflow then refreshes configured profiles on a schedule (daily for Free, with an hourly minimum for Pro) and can be dispatched manually. Its updates to the SVGs are atomic. Pro publication also enables authenticated, profile-scoped workflow health telemetry and a separate analytics badge in the README.

The editor writes the generated embed to your profile repository's README.md; you can also copy it manually. Replace yourusername if using this example:

<picture>
  <source
    media="(prefers-color-scheme: dark)"
    srcset="
      https://raw.githubusercontent.com/yourusername/yourusername/gitascii/profiles/default/dark.svg
    "
  />
  <source
    media="(prefers-color-scheme: light)"
    srcset="
      https://raw.githubusercontent.com/yourusername/yourusername/gitascii/profiles/default/light.svg
    "
  />
  <img
    alt="GitAscii Profile"
    src="https://raw.githubusercontent.com/yourusername/yourusername/gitascii/profiles/default/dark.svg"
    width="100%"
  />
</picture>

The two URLs remain stable as the repository workflow updates their contents. Additional profiles use profiles/[slug]/dark.svg and light.svg.

The HTTP rendering API (/api/[username]) remains available for previews, custom integrations, and Pro dynamic rules. It is not the default README embed.

For Pro profiles, keep the generated GitAscii badge directly below the <picture>. Its analytics count badge fetches observed by GitAscii (usually GitHub Camo cache refreshes), not exact human views or unique visitors. GitHub's image proxy does not expose reliable viewer geography, browser, device, or identity. Pro health data comes separately from authenticated workflow runs.

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!

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.

Local browsing and editing work without connecting your own integrations. To test sign-in and Publish to GitHub, copy .env.example to .env.local and set the GitHub OAuth, GitHub App, and SESSION_SECRET values. Set DATABASE_URL for PostgreSQL persistence and the Upstash variables for Redis-backed features; Stripe and Resend are needed only for their respective Pro billing and email flows. The publisher writes to a GitHub profile repository, so use an account and repository intended for testing.

All available scripts configured in package.json:

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.

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