Skip to main content

Quickstart

GitAscii v2 publishes SVG files to your own gitascii branch. The HTTP API remains available for previews and programmatic rendering; the normal profile README uses the GitHub-hosted files.

1. GitHub-native profile publishing

Open the visual editor, sign in, authorize the GitHub App for your special profile repository (YOUR_USERNAME/YOUR_USERNAME), and select Publish to GitHub. GitAscii creates the repository if needed, publishes an initial dark/light SVG pair and configuration, writes the README embed, and installs .github/workflows/gitascii.yml on the default branch. The generated embed uses these stable files:
The <picture> version switches themes automatically. The workflow refreshes saved profiles from current GitHub data on a schedule or manual dispatch; the README URL stays the same. Free runs are scheduled daily. Pro runs are scheduled hourly, subject to the configured minimum interval for scheduled publication. Additional profiles use their own profiles/[slug]/ directory and gitascii_[slug].json configuration. If Pro dynamic rules are enabled for the default profile, the generated default embed uses the HTTP API with ?dynamic=1 to select a profile at request time.

2. Programmatic Engine Rendering (TypeScript)

If you are building custom tools, CLI banners, or Next.js edge routes, import the core engine from @/engine:

3. Rendering an Individual Widget Standalone

To isolate and render a single widget without creating a full multi-widget layout: