Website
The landing page lives in site/: Astro 5 + Tailwind CSS v4, static output, published at the root of https://bakasub.silvatti.com.br (GitHub Pages with a custom domain, base: '/'; the domain is set in the repository’s Pages settings, and public/CNAME keeps it on every deploy). It is a separate npm project, outside the root package: its CI installs only site/, so the app’s postinstall (sidecars, native rebuilds) never runs there.
cd sitenpm installnpm run dev # http://localhost:4321/ (docs at /docs/)npm run build # astro check + static build into site/dist (+ Pagefind search index)npm run preview # serves site/dist at /Brand sources, read in place
The site has no copy of the palette, the fonts or the logos. site/astro.config.ts aliases the folders outside site/ and lists them in vite.server.fs.allow:
| Alias | Folder | Used for |
|---|---|---|
@brand |
src/shared/brand |
fonts.css, tokens.css, theme.css (see brand tokens) |
@resources |
resources |
icon.svg: favicon, nav and footer mark |
@assets |
src/renderer/src/assets |
logo.svg: hero lockup |
@docs |
docs |
README logos |
site/tsconfig.json mirrors the aliases for astro check. In dev, Vite serves these files from their origin (/@fs/...); in the build they are emitted as hashed files in dist/_astro/. build.assetsInlineLimit: 0 keeps SVGs as files instead of data URIs.
src/shared/brand/fonts.css imports @fontsource-variable/* by bare name; resolved from its own folder, that would reach the root node_modules. The config pins both packages to site/node_modules, and site/package.json declares them, so the fonts are self-hosted from the site’s own install.
site/package.json overrides vite to the version Astro 5 ships (6.x): @tailwindcss/vite would otherwise pull a newer Vite, and two copies break the plugin types in astro check.
Logos
resources/icon.svg (square app icon) and src/renderer/src/assets/logo.svg (icon + “Bakasub” wordmark, transparent background) draw the same mark; the lockup embeds the icon. The site uses the icon wherever a small square mark fits (favicon, nav, footer) and the lockup in the hero. docs/bakasub-logo-*.svg carry a localized tagline baked into the image and an opaque background: they stay for the READMEs, the site renders its text as HTML so it can be translated.
Structure
src/layouts/Base.astro:<html lang>,<head>(title, description, favicon, canonical,hreflangalternates, Open Graph withog:locale), global stylesheet.src/components/:Nav,Hero,Screenshots,Features,Pipeline,Privacy,Footer,GitHubIcon,carousel/; shared piecesSectionHeader(kicker,<h2>, lead) andIcon.src/data/screenshots.ts: the carousel slides (see below).src/data/features.ts: the feature grid, the three pipeline steps and the privacy points, as{ id, icon, title, body }wheretitle/bodyareTranslationKeys (no text in components).src/data/icons.ts: the stroke icons (24×24 paths) thatIcon.astrodraws.src/styles/global.css: Tailwind, then the shared brand files, then base rules. No token value is defined here.src/components/HomePage.astro: the whole page for one locale;src/pages/index.astro(EN) andsrc/pages/pt/index.astro(PT) only passlocale.src/i18n/: see Languages. Components take alocaleprop.src/docs/,src/content.config.ts,src/components/docs/,src/styles/docs.css: the documentation pages, see Documentation.
Download buttons are components/DownloadButtons.astro (in the hero), fed by src/lib/release.ts; see Downloads.
Languages
English at /, Brazilian Portuguese at /pt/ (src/pages/pt/). The config has no Astro i18n block: Starlight refuses to run next to one that has its own locales, and inferring its locales from it would generate /pt/docs/* fallback pages for the English-only docs. Locale URLs are therefore built by src/i18n/index.ts (localeHomePath, localeHomeUrl, sitePath), never by astro:i18n.
src/i18n/en.tsis the reference dictionary;Dictionaryderives from its keys.src/i18n/pt.tsis declaredsatisfies Dictionary, so a missing key or a keyen.tsdoes not have failsastro check/tsc(hencenpm run build).src/i18n/index.ts:locales,localeInfo(BCP 47 tagen/pt-BR,og:locale, endonym, short code),useTranslations(locale),format().links.tsholds the language-independent URLs.Base.astrosets<html lang>from the tag and emits reciprocal<link rel="alternate" hreflang>for every locale plusx-default(EN); URLs come fromlocaleHomeUrl(), so they followsite+base.- The
Navswitcher is two plain links (EN/PT, no JS) to each locale’s home, withhreflang,langand the endonym as accessible name; the current one carriesaria-current="page". The brand link also goes to the current locale’s home. - PT wording follows
README-pt.md. The hero keeps the transparent lockup in both languages; the tagline is the translated HTML kicker (see Logos). Links to the user guide and to/docssay they are in English (Docs (em inglês)as the accessible name in the nav,Documentação (em inglês)in the footer).
Adding a locale: add it to locales and localeInfo in src/i18n/index.ts, write src/i18n/<code>.ts with satisfies Dictionary, and add src/pages/<code>/index.astro rendering <HomePage locale="<code>" />.
Screenshot carousel
components/carousel/Carousel.astro renders the slides of src/data/screenshots.ts ({ id, src?, alt, caption, icon? }), no library.
- Without JS it is a horizontal strip with
overflow-x: autoandscroll-snap-type: x mandatory: touch, trackpad and the arrow keys (the track is focusable) all work, and the controls stayhidden. carousel.ts(progressive enhancement) shows previous/next buttons and dots, handlesArrowLeft/ArrowRight/Home/Endanywhere inside the carousel, and tracks the active slide with anIntersectionObserver(threshold 0.6) to setaria-currenton the dot and disable the buttons at the ends. No autoplay. Programmatic scrolls aresmoothunlessprefers-reduced-motion: reduce, in which case they jump; the CSSscroll-behaviorfollows the same media query.- ARIA:
<section aria-roledescription="carousel" aria-label>, each slide a<figure role="group" aria-roledescription="slide" aria-label="2 of 5">with a visiblefigcaption. - Strings come from i18n:
carousel.*for the chrome ({index}/{total}filled byformat()fromsrc/i18n),screenshots.<id>.caption|altper slide.
Adding a screenshot: put a 16:10 image (1600x1000) in site/public/screenshots/ and set src to its file name in src/data/screenshots.ts. Without src the slide shows a placeholder (app window frame, faded icon, caption); no component changes either way.
Capturing the screenshots
The images are taken from the real renderer, not mock-ups, by scripts/screenshots/:
vite.config.mtsservessrc/rendererin a plain browser, injectingmock-api.tsbeforemain.tsxand dropping the CSP (dev-only, never part of the app build).mock-api.tsis an in-memorywindow.apityped againstBakaSubApi(IPC contract changes break it at type level). It reusesBUILTIN_PRESETSand answers with copies (structuredClone), like the real IPC. The library is a fictional show (“Starlight Courier”) with original SVG art fromart.ts: no TMDB image or real release appears on the site.capture.mjsstarts that server, drives each scene with Playwright (1600x1000,en-US, UTC, reduced motion) and writessite/public/screenshots/<id>.png.
npm i --no-save --ignore-scripts playwright-core # once; not a project dependencynode scripts/screenshots/capture.mjs # all scenesnode scripts/screenshots/capture.mjs --only=cost,queue --chrome=/path/to/chromeScenes find elements by their English labels (“Browse files”, “Continue”, “Estimate cost”); renaming one of them in the app means updating capture.mjs. A failing scene saves the page to the OS temp folder and the script exits non-zero. Re-run it after visible UI changes.
Documentation
/docs/ publishes every docs/*.md with Starlight (0.37, the last line that supports Astro 5). English only. The files are read in place; nothing is copied into site/ and the docs keep no frontmatter, so they still read well on GitHub.
- Loader (
src/docs/loader.ts, used bysrc/content.config.ts): Astro’sglobloader on../docs/*.md(subfolders are not published). Ids are slugs:user-guide.mdis the index (docs), anything elsedocs/<name>. It derives the frontmatter Starlight requires:titlefrom the first# Heading,descriptionfrom the first paragraph,editUrlto the GitHub editor. Frontmatter written in a doc still wins. - Remark plugin (
src/docs/remark-repo-docs.ts, only for files directly indocs/): drops the leading# Heading(Starlight renders the title) and rewrites links:./jobs.md#x→/docs/jobs/#x, any other relative link (../src/...,../README.md) → its GitHub URL onmain. Heading ids follow github-slugger as on GitHub, so anchors written for GitHub keep working. - Sidebar (
src/docs/sidebar.ts): Guide (user-guide,reporting-issues) and Development (every other file, in a reading order; a newdocs/*.mdnot listed there is appended alphabetically). The build fails if the list names a file that no longer exists. - Theme:
src/styles/docs.cssmaps Starlight’s--sl-*variables onto the brand tokens (after@brand/fonts.cssand@brand/tokens.css). Dark only:components/docs/ThemeProvider.astropinsdata-theme="dark"andThemeSelect.astroremoves the picker. - Route middleware (
src/docs/route-middleware.ts): Starlight only takes a favicon frompublic/, so the<link rel="icon">is pointed at the bundledresources/icon.svg; it also adds the landing’sog.png. - Search: Pagefind index, built by Starlight at
npm run build(not available innpm run dev). Starlight also writessitemap-index.xml. - Effects on the landing: Starlight forces
scopedStyleStrategy: 'where'for the whole site (scoped styles become:where(.astro-xxx)instead of[data-astro-cid-xxx]; no visual change, checked against screenshots).prefetch: falsein the config keeps Starlight from adding its prefetch script to every page.disable404Route: truekeeps Starlight’s 404 off GitHub Pages’ site-wide404.html.
Nav (Docs) and footer link to /docs/. To add a page, create docs/<name>.md starting with # Title, link it from other docs with ./<name>.md, and add it to the order in src/docs/sidebar.ts if it is user-facing or needs a specific place.
Content sections
Features (7 cards, the README “What it does” list), Pipeline (Extract → Translate → Re-mux, an <ol> with inline SVG arrows) and Privacy (no account, no telemetry, local key and files, plus what does leave the machine) take every string from features.*, pipeline.* and privacy.* in en.ts. Each section is a <section aria-labelledby> on its <h2>, items are <h3>; anchors #features, #how-it-works, #privacy.
Claims must match the README and the docs, never go further: the privacy copy follows user guide › Privacy (it links there), the pipeline follows jobs. Change the docs first, then the site.
Downloads
src/lib/release.ts calls GET /repos/lsilvatti/bakasub/releases/latest once per build (memoized, 10 s timeout). That endpoint skips drafts and prereleases; the code checks it again. GITHUB_TOKEN is sent when present (CI) to avoid the anonymous rate limit.
Assets are matched by extension against the artifactName of electron-builder.yml: *-setup.exe (nsis) and *.AppImage. The version shown is the tag without v. If the artifact names or extensions change, update the two regexes in release.ts.
Any failure (API down, rate limit, no release, a missing asset) logs a [release] warning and falls back to https://github.com/lsilvatti/bakasub/releases for both buttons, with no version label: the build never fails because of the API.
The version is baked in at build time, which is why a release triggers a deploy (below).
Deploy
.github/workflows/site.yml builds site/ and publishes site/dist to GitHub Pages (configure-pages, upload-pages-artifact, deploy-pages).
| Trigger | When |
|---|---|
push to main |
Paths: site/**, docs/** (pages and logos), resources/icon.svg, the brand sources (src/shared/brand/**, logo.svg) |
release: [published] |
Refreshes the version and links of the download buttons |
workflow_dispatch |
Manual redeploy |
- Only
site/is installed (npm ci --ignore-scriptswithworking-directory: site, cache keyed onsite/package-lock.json): the rootpostinstallnever runs. - Permissions:
contents: readfor the build;pages: write+id-token: writeonly on the deploy job.concurrency: pageswithout cancelling a deploy in flight. - The release workflow creates a draft release; publishing it by hand in the GitHub UI fires
release: published. A release published by a workflow usingGITHUB_TOKENdoes not trigger other workflows: in that case run Site manually (workflow_dispatch). - One-time setup (repository owner): Settings › Pages › Build and deployment › Source: GitHub Actions. Until then the deploy job fails.
- Rollback: re-run an earlier successful run of the workflow, or revert the commit on
main. The site is stateless; unpublishing is Settings › Pages.
Social image
public/og.png (1200×630) is generated from the logo lockup by scripts/og-image.mjs (sharp, already a dependency of Astro) and committed: npm run og in site/ after a brand change. Base.astro emits og:image (absolute URL from site + BASE_URL), og:image:width/height/alt, og:site_name and the twitter:card=summary_large_image set. The tagline in the image is English only and rendered with a system font (DejaVu Sans on Linux); check the PNG after regenerating.
Replacing the screenshots
- Capture again with
scripts/screenshots/capture.mjs(see Capturing the screenshots), or drop your own 1600×1000 PNGs intosite/public/screenshots/with the same names as the ids insrc/data/screenshots.ts. - For a new slide, add it to
src/data/screenshots.tsplus itsscreenshots.<id>.caption|altkeys inen.tsandpt.ts. npm run buildinsite/, commit the PNGs: they live in the repo, no step in CI produces them.