voyvodka/LumaSync-Site

LumaSync-Site

Marketing site, docs, and blog for LumaSync — the tray-first open-source ambilight + Philips Hue desktop app.

• Site: https://lumasync.app
• App repo: https://github.com/voyvodka/LumaSync

Stack

• Astro 6 + MDX content collections (docs, compare, legal, blog)
• Pagefind for offline in-browser search; Umami for cookie-free analytics
• Cloudflare Pages (direct-upload via wrangler) + Cloudflare DNS
• IBM Plex Sans / Mono (self-hosted WOFF2, preloaded)
• No secrets bundled; the site never talks to the desktop app

Develop

Requires Node 22+ and pnpm (pinned via packageManager in package.json).

pnpm install
pnpm dev        # http://localhost:4321
pnpm lint       # prettier --check
pnpm check      # astro check (type-check + content schema)
pnpm build      # astro build + pagefind index

Deploy

Every push to main triggers .github/workflows/deploy.yml, which lint- and type-checks, builds, and ships dist/ to Cloudflare Pages.

Required repo secrets for CI: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID.

License

• Code (Astro components, layouts, CI, styling) — MIT
• Content (MDX under src/content/, docs, comparisons, blog) — CC BY 4.0

See /license for the public-facing summary and LICENSE for the full text.

Contributing

Issues and PRs welcome — see CONTRIBUTING.md for scope, local preview, and commit conventions. For app-level bugs (firmware, USB pipeline, Hue streaming), file against the LumaSync app repo instead.

Security

Report vulnerabilities through GitHub's Private Vulnerability Reporting — see SECURITY.md or /.well-known/security.txt.

Changelog — lumasync-site

This is the changelog for the marketing/docs site at lumasync.app. The LumaSync app's own release notes live in the app repo and surface on /changelog — site versions track independently from app versions.

The site follows Semantic Versioning at its own cadence; bumping the LumaSync app submodule does not require bumping the site version.

[1.1.1] — 2026-04-27

Fixed

• Favicon: regenerated public/favicon.svg to match the brand monogram on a 64×64 viewBox with a heavier mark stroke so Google's 16×16 search-result favicon scaling stays legible — the previous thin-slash 32×32 version was getting visually collapsed.
• PNG favicon fallbacks: added /favicon-32.png and /favicon-192.png Astro endpoints (Resvg-rendered from app-icon.svg) plus matching <link rel="icon" sizes="..."> entries in BaseLayout.astro and the webmanifest icon array, so search engines that prefer raster favicons get a clean, sized rasterization instead of scaling SVG themselves.
• Release notes wrap: switched prettier proseWrap to "never" for *.md and *.mdx, and rewrote CHANGELOG.md with one-bullet-per-line so GitHub's Releases renderer no longer breaks bullet text mid-line.

Documentation

• CLAUDE.md: project-level governance file added — public-repo privacy rules, pre-commit checklist for sensitive content, commit hygiene reminders. Future agent passes consult this before staging.
• CHANGELOG.md: removed internal analytics snapshots (raw GSC index counts, AI-crawler hit counts, Web Analytics percentile values) from the v1.1.0 entry. Discoverability work is now described qualitatively. Internal observability metrics live in private notes outside the repo.

[1.1.0] — 2026-04-27

Discoverability overhaul

A site audit surfaced a sitemap-vs-canonical 308 redirect chain (Astro emitted slash-less URLs; Cloudflare Pages redirected to slash-suffixed URLs) that was throttling Google's indexing of sub-pages. This release fixes the root cause and adds the entity / intent / structure scaffolding AI overviews need to disambiguate "lumasync".

Added

• Section index pages for all six docs groups (/docs/getting-started/, /docs/hue/, /docs/usb-leds/, /docs/ambilight/, /docs/advanced/, /docs/reference/) — single shared dynamic route with group-specific lede + keyword padding.
• SoftwareApplication JSON-LD schema on the homepage (was only on /download/) so AI overviews can anchor "what is LumaSync" to a concrete software entity.
• Article JSON-LD schema on each compare leaf (/compare/wled/, /compare/hue-sync/, /compare/hyperion/, /compare/prismatik/).
• "See how LumaSync compares" section on the homepage with four competitor cards linking to the comparison pages — feeds homepage authority to the previously-orphaned compare leaves.
• ## Disambiguation section in llms.txt listing what LumaSync is not (Sync-on-Luma, Luma Labs, luma-sync.com, Lapster LUMA Sync). Mirrored as inline microcopy on the homepage compare CTA.
• 11 search-intent redirect aliases in astro.config.mjs: /quick-start, /docs/getting-started/quick-start, /led-calibration, /docs/concepts/led-calibration, /hue-pairing, /hue-entertainment, /usb-setup, /serialport, /screens, /multi-monitor, /compare-tools.
• Sublede paragraph on /compare/ index naming the four alternatives in bold for "lumasync alternatives" search intent.

Changed

• trailingSlash: 'always' in astro.config.mjs (was 'never') so sitemap URLs and <link rel="canonical"> match Cloudflare Pages' trailing-slash redirect target. This is the load-bearing fix for the GSC indexation gap on sub-pages.
• Organization schema extended with description, alternateName (["LumaSync", "Luma Sync"]), slogan, keywords, founder (Person with sameAs), and broader sameAs (3 entries, was 1).
• SoftwareApplication.operatingSystem now an array (["macOS", "Windows", "Linux"]) instead of a comma-joined string — better validator and AI-engine parse.
• H2 heading rewrites for query-keyword alignment: install.mdx Prerequisites → System requirements; hardware-checklist.mdx "For the USB LED path" → "USB LED path — WS2812B strips and controllers"; controllers.mdx adds "Supported chipsets — CH340 and FT232" above the existing chipset table; tuning.mdx adds a "Quick reference — four tuning knobs" overview table at the top; shortcuts.mdx "Global (app-wide)" → "Global shortcuts (app-wide)".
• MDX H2 anchors for direct linking: first-setup.mdx "What you'll do" → "Quick start"; calibration.mdx adds "LED calibration" H2 + intro paragraph.
• Landing-page meta-tag rewrites for keyword coverage: /download/ title → "Download LumaSync" and description adds DMG / MSI / AppImage installer keywords; /community/ title → "Community & Support" with help/bugs phrasing; /changelog/ title → "Changelog — release notes" with version-history phrasing.
• Section-index ledes strengthened: hue/ prepends "Set up"; ambilight/ rewritten to explicitly mention macOS/Windows/Linux screen-recording permissions, latency, and FPS.
• LAST_MODIFIED middleware constant bumped to today's RFC 1123 stamp for content-edit deploys (was tied to app release dates only).
• updated: frontmatter bumped to 2026-04-27 on the seven MDX files touched.

Fixed

• Sitemap canonical mismatch — URLs in sitemap-0.xml now match the live URL 1:1 (no 308 chain). Verified locally: dist/sitemap-0.xml emits https://lumasync.app/compare/wled/ (slash); the live URL serves 200 directly.
• /docs/<group>/ 404s — group root paths now resolve to index pages instead of falling through to the catch-all 404.

Infrastructure

• .gitignore adds .wrangler/ so local Cloudflare dev cache stays out of git.

Manual follow-ups (post-deploy)

These require human action and are tracked here so the next pass can verify completion:

1. GSC → Sitemaps → resubmit sitemap-index.xml.
2. GSC → URL Inspection → Request Indexing on 8 priority URLs: /, /download/, /docs/, /compare/, /compare/hue-sync/, /compare/wled/, /docs/getting-started/first-setup/, /docs/usb-leds/calibration/.
3. Bing Webmaster Tools → "Import from Google Search Console" (instant verification because GSC is already DNS-verified).
4. chatgpt.com → search "what is lumasync.app" + "lumasync vs hue sync" to trigger ChatGPT-User fetch.
5. perplexity.ai → similar queries to trigger PerplexityBot fetch.
6. (Future) Open Mastodon / Bluesky profiles with rel="me" linking back to lumasync.app and add to Organization.sameAs.

[1.0.0] — 2026-04-21

Initial launch

• Astro 6 SSG, Cloudflare Pages, custom domain lumasync.app with www → apex redirect.
• 34 routes: homepage, /download/, /changelog/, /community/, /license/, /privacy/, /compare/ index + 4 leaves, /docs/ index + 19 leaves.
• JSON-LD schemas (Organization, WebSite, Article, ItemList, FAQPage, CollectionPage, BreadcrumbList) across all relevant routes.
• Pagefind static search index, Markdown for Agents content negotiation (Accept: text/markdown serves .md siblings), llms.txt and llms-full.txt for AI retrieval grounding.
• robots.txt with Cloudflare Content-Signal directive — training bots blocked, retrieval bots allowed.