SEO & GitHub Pages Setup (One-Time, Manual)

This file documents the one-time manual steps the repository owner must perform to activate GitHub Pages and maximize Google discoverability. Everything in the repo itself (Jekyll site, sitemap, robots.txt, workflow, English docs) is already prepared.

1. Enable GitHub Pages (Settings)

Go to Settings → Pages in lxndrJ/TDisplayS3_Adventure.
Under Build and deployment → Source, select GitHub Actions (NOT “Deploy from a branch” - the repo ships a ready-made .github/workflows/pages.yml).
Save. The workflow runs automatically on the next push to main (or manually via Actions → Deploy Docs to GitHub Pages → Run workflow).

The first deploy happens after this PR is merged to main. The site will be live at: https://chipnplay.pandango.de/

1b. Custom Domain (Already Configured)

The site is served from the custom domain chipnplay.pandango.de (root). The repo already contains:

docs/CNAME with chipnplay.pandango.de
docs/_config.yml with url: "https://chipnplay.pandango.de" and baseurl: ""

Make sure in Settings → Pages:

Custom domain = chipnplay.pandango.de
Enforce HTTPS = ✅ enabled (recommended)

If you ever switch back to lxndrJ.github.io/TDisplayS3_Adventure/, set baseurl: "/TDisplayS3_Adventure" and url: "https://lxndrJ.github.io" in docs/_config.yml and remove docs/CNAME.

2. Set Repository Metadata (Settings → General)

These fields power Google’s understanding of the repo and appear in search results / link previews.

Field	Value
Description	`Modular mini-game engine and game collection for the LilyGo T-Display-S3 (ESP32-S3, 320x170 ST7789, 2 buttons): Eldoria, Neon Run, Neon Shard, Chip Slide, Neon Dash. PlatformIO + Arduino + TFT_eSPI. Docs on GitHub Pages.`
Website	`https://chipnplay.pandango.de/`
Topics	`esp32`, `esp32-s3`, `t-display-s3`, `lilygo`, `tft_espi`, `platformio`, `arduino`, `embedded`, `game`, `retro`, `cyberpunk`, `esp32-game`, `mini-game`

Equivalent `gh` CLI commands (if you prefer)

# Description + homepage
gh api -X PATCH repos/lxndrJ/TDisplayS3_Adventure \
  --field description="Modular mini-game engine and game collection for the LilyGo T-Display-S3 (ESP32-S3, 320x170 ST7789, 2 buttons): Eldoria, Neon Run, Neon Shard, Chip Slide, Neon Dash. PlatformIO + Arduino + TFT_eSPI. Docs on GitHub Pages." \
  --field homepage="https://chipnplay.pandango.de/"

# Topics (replaces the full list)
gh api --method PUT repos/lxndrJ/TDisplayS3_Adventure/topics \
  -H "Accept: application/vnd.github.mercy-preview+json" \
  --field 'names[0]=esp32' \
  --field 'names[1]=esp32-s3' \
  --field 'names[2]=t-display-s3' \
  --field 'names[3]=lilygo' \
  --field 'names[4]=tft_espi' \
  --field 'names[5]=platformio' \
  --field 'names[6]=arduino' \
  --field 'names[7]=embedded' \
  --field 'names[8]=game' \
  --field 'names[9]=retro' \
  --field 'names[10]=cyberpunk' \
  --field 'names[11]=esp32-game' \
  --field 'names[12]=mini-game'

Upload a 1280 x 640 px PNG/JPG. Suggested content:

Dark cyberpunk background with neon accents (cyan #00F0FF, magenta #FF2BD6)
Text: “TDisplayS3 Adventure” + subtitle “Mini-Game Platform for LilyGo T-Display-S3”
Maybe small screenshots of the 5 games as thumbnails

This image appears when the repo / Pages site is shared on social media and in link previews - it significantly improves click-through rate.

A quick way to generate one (if you have Python + PIL):

from PIL import Image, ImageDraw, ImageFont
img = Image.new("RGB", (1280, 640), (11, 14, 20))
d = ImageDraw.Draw(img)
# ... draw neon title text, game names, etc.
img.save("social-preview.png")

Then upload it in Settings → General → Social preview → Upload an image.

4. Submit the Sitemap to Google Search Console

After the Pages site is live (step 1) and reachable:

Go to Google Search Console.
Add property → URL prefix: https://chipnplay.pandango.de/
Verify ownership (GitHub Pages serves a google-site-verification meta tag only if you add it - alternative: verify via the GitHub repo DNS/HTML method, or use the Domain property type if you own a domain).
- Simplest for a *.github.io subpath: use the HTML file method is NOT possible on Pages; instead verify via DNS if you add a custom domain, or use the HTML tag method by adding the google-site-verification meta tag to docs/_layouts/default.html (see below).
Once verified, go to Sitemaps and submit: https://chipnplay.pandango.de/sitemap.xml (auto-generated by the jekyll-sitemap plugin).

Optional: Google verification meta tag

If Google asks for an HTML-tag verification, add this line to <head> in docs/_layouts/default.html and docs/_layouts/home.html:

<meta name="google-site-verification" content="YOUR_VERIFICATION_CODE" />

5. What Is Already Automated in the Repo

SEO & GitHub Pages Setup | TDisplayS3 Adventure

6. After Deploy: Verify & Monitor

# Check the site is live
curl -sI https://chipnplay.pandango.de/ | head -3

# Check the sitemap
curl -s https://chipnplay.pandango.de/sitemap.xml | head -20

# Check robots.txt
curl -s https://chipnplay.pandango.de/robots.txt

Then in Google Search Console:

URL Inspection → request indexing for the homepage and each wiki page.
Performance → monitor impressions/clicks over the next weeks.

7. Optional: Custom Domain (for even better SEO)

If you ever buy a domain (e.g. tdisplays3-adventure.dev):

Add a docs/CNAME file containing just the domain:
```
tdisplays3-adventure.dev
```
In your DNS provider, add:
- A records pointing to GitHub Pages IPs: 185.199.108.153, 185.199.109.153, 185.199.110.153, 185.199.111.153
- or a CNAME record: www → lxndrJ.github.io
In Settings → Pages → Custom domain, enter the domain and enable Enforce HTTPS.
Update url: in docs/_config.yml and the sitemap URL in docs/robots.txt.

A custom domain ranks better than a *.github.io subpath because it looks more “established” to Google.

SEO & GitHub Pages Setup