Added a README, CONTRIBUTING and 3 repo skills

2026-04-19 19:32:02 +01:00
parent b7233c694c
commit fbfb7505e3
5 changed files with 1193 additions and 0 deletions
--- a/.agents/skills/unyo-components/SKILL.md
+++ b/.agents/skills/unyo-components/SKILL.md
@@ -0,0 +1,245 @@
+---
+name: unyo-components
+description: Modify the Unyo landing page components — Hero section with mascot and CTAs, FeatureGrid with 6 feature cards, ScreenshotGallery carousel with center-scaling and lightbox, and the custom landing page footer. Use this skill whenever the user wants to change landing page content, layout, animations, add or remove features from the grid, update screenshots, adjust the mascot size or effects, change CTA buttons, modify the footer, or asks how the landing page is assembled.
+---
+
+# Unyo Components Guide
+
+This skill covers how to modify the landing page components for the Unyo website. The landing page is a custom React page that does not use Docusaurus's blog or page plugins — it's hand-built with CSS Modules.
+
+## Landing Page Architecture
+
+The landing page is assembled in `website/src/pages/index.js`:
+
+```
+<Layout>
+  <main className={styles.main}>
+    <Hero />
+    <div className={styles.divider} />
+    <FeatureGrid />
+    <div className={styles.divider} />
+    <ScreenshotGallery />
+  </main>
+  <footer className={styles.landingFooter}>
+    ...custom footer...
+  </footer>
+</Layout>
+```
+
+Key architectural points:
+
+1. **`<Layout>`** wraps everything — provides the navbar. Docusaurus's default footer is **intentionally disabled** (no `footer` in `themeConfig`). The only footer on the landing page is the custom `<footer>` in `index.js`.
+
+2. **The custom `<footer>`** is a sibling of `<main>`, not nested inside it. This was done so it sits in the correct DOM position and doesn't conflict with Docusaurus's Layout component.
+
+3. **`<main>` has `background-color: #0d0a1a`** via `index.module.css`. The footer has its own gradient that bleeds from this color.
+
+## Component Map
+
+| Component | Directory | What it renders |
+|-----------|-----------|-----------------|
+| Hero | `src/components/Hero/` | Mascot image, tagline, badge, two CTA buttons |
+| FeatureGrid | `src/components/FeatureGrid/` | 6 feature cards in a 3-column grid |
+| ScreenshotGallery | `src/components/ScreenshotGallery/` | Horizontal scroll carousel with center emphasis, arrow buttons, lightbox |
+| Landing footer | defined inline in `src/pages/index.js` | Logo, tagline, links, copyright |
+| Page layout | `src/pages/index.js` + `index.module.css` | Vertical sections with gradient dividers |
+
+Each component has:
+- `index.js` — React component
+- `styles.module.css` — scoped CSS Module styles
+
+## Hero Component
+
+**Files**: `website/src/components/Hero/index.js`, `styles.module.css`
+
+### Structure
+
+```
+<section .hero>
+  <div .heroGlow />          (radial gradient backdrop)
+  <div .heroNoise />          (subtle SVG noise texture)
+  <div .container>            (flex row: text left, mascot right)
+    <div .heroContent>
+      <span .badge>           ("Open Source • Ad-Free • Multi-Platform")
+      <h1 .heroTitle>         ("Your anime & manga, your way.")
+      <p .heroSubtitle>       (description text)
+      <div .heroCtas>
+        <Link .ctaPrimary>    ("/docs" — Get Started →)
+        <Link .ctaSecondary>  ("https://github.com/K3vinb5/Unyo" — GitHub)
+      </div>
+    </div>
+    <div .heroMascotWrap>
+      <div .mascotRing />    (purple radial gradient ring)
+      <img .heroMascot />     (robot mascot image)
+    </div>
+  </div>
+</section>
+```
+
+### Common changes
+
+**Change mascot image**: Replace `website/static/img/mascot.png`
+
+**Change mascot size**: Edit `.heroMascot` width/height in `styles.module.css`. Current: `390px`. Responsive breakpoints at 996px (280px) and 600px (240px). Scale `.mascotRing` proportionally (currently 490px / 360px / 300px).
+
+**Change CTA links**:
+- "Get Started" link: edit the `to` prop on the `<Link>` component (currently `/docs`)
+- "GitHub" link: edit the `href` prop (currently `https://github.com/K3vinb5/Unyo`)
+
+**Change headline/subtitle**: Edit the JSX text directly in `index.js`
+
+**Animations**:
+- Page load: `fadeSlideUp` on text content, `fadeSlideRight` on mascot
+- Mascot float: `mascotFloat` (3s ease-in-out infinite, translateY -14px)
+- Ring pulse: `ringPulse` (4s ease-in-out infinite, opacity + scale)
+
+## FeatureGrid Component
+
+**Files**: `website/src/components/FeatureGrid/index.js`, `styles.module.css`
+
+### Structure
+
+The features are defined as a JS array inside `index.js`:
+
+```js
+const features = [
+  { title: 'Anime Streaming', description: '...', icon: (<svg>...</svg>) },
+  { title: 'Manga Reader', description: '...', icon: (<svg>...</svg>) },
+  // ...6 items total
+];
+```
+
+### Common changes
+
+**Add a feature**: Add an object to the `features` array with `title`, `description`, and `icon` (inline SVG). Max recommended: 6 (fills the 3-column grid evenly). For 8, the grid wraps to 2 rows of 4 if you change the grid to `repeat(4, 1fr)`.
+
+**Remove a feature**: Delete the object from the array. The grid handles any count via `grid-template-columns: repeat(3, 1fr)` with auto-flow.
+
+**Change a feature card's text/icon**: Edit the corresponding object in the array.
+
+**Card hover effect**: `.card:hover` in `styles.module.css` — currently does `translateY(-4px)`, border glow, and box-shadow.
+
+**Animation**: Cards use `cardAppear` keyframe with staggered delay via `animationDelay` prop (`${i * 0.08}s`).
+
+**Grid layout**: Change `grid-template-columns` in `.grid`:
+- 3 columns: `repeat(3, 1fr)` (current)
+- 2 columns: `repeat(2, 1fr)`
+- Responsive breakpoints at 996px (2 cols) and 600px (1 col)
+
+## ScreenshotGallery Component
+
+**Files**: `website/src/components/ScreenshotGallery/index.js`, `styles.module.css`
+
+### Structure
+
+Screenshots are defined as a JS array:
+
+```js
+const screenshots = [
+  { src: '/img/screenshots/home.png', alt: 'Unyo home screen' },
+  { src: '/img/screenshots/anime-1.png', alt: '...' },
+  // ...8 total
+];
+```
+
+### Center-emphasis carousel
+
+The carousel uses an `IntersectionObserver`-like approach via `onscroll` to track which slide is nearest to the center:
+
+- **Active slide**: `scale(1)`, `opacity: 1`, purple border glow
+- **Inactive slides**: `scale(0.88)`, `opacity: 0.65`
+- Transition: `all 0.4s cubic-bezier(0.25, 0.46, 0.45, 0.94)`
+
+The active index is calculated in `updateScrollState`:
+```js
+const childWidth = 380 + 20; // slide width + gap
+const center = el.scrollLeft + el.clientWidth / 2;
+const idx = Math.round((center - childWidth / 2) / childWidth);
+```
+
+### Common changes
+
+**Add a screenshot**: 
+1. Place the image in `website/static/img/screenshots/`
+2. Add an object to the `screenshots` array
+
+**Remove a screenshot**: Delete the object from the array
+
+**Change screenshot width**: Edit `.screenshot { width: 380px }` in `styles.module.css`. Also update `childWidth` in `index.js` to match (`width + gap`).
+
+**Change carousel behavior**: The scroll buttons use `scrollBy({ left: dir * 340 })` — adjust the scroll distance if you change screenshot width.
+
+**Lightbox**: Clicking a screenshot opens `<div className={styles.lightbox}>` — a full-screen overlay with the full-size image. Click anywhere to close. The close button is in the top-right corner.
+
+## Landing Footer
+
+**File**: `website/src/pages/index.js` (inline in JSX), styles in `src/pages/index.module.css`
+
+The footer is **not** the Docusaurus default footer. It's a custom `<footer>` element defined directly in `index.js` with these sections:
+
+1. Logo + name (`.footerLogo`)
+2. Tagline (`.footerTagline`)
+3. Links row (`.footerLinks`): GitHub, Releases, GPL-3.0 License
+4. Copyright (`.footerCopy`)
+
+### Common changes
+
+**Add/remove footer links**: Edit the `<div className={styles.footerLinks}>` block in `index.js`
+
+**Change footer background**: Edit `.landingFooter { background }` in `index.module.css`. Current gradient: `linear-gradient(180deg, #0d0a1a 0%, #0f0b22 40%, #1a0e2e 100%)`
+
+**Change footer border**: Edit `.landingFooter { border-top }` — currently `1px solid rgba(168, 85, 247, 0.15)`
+
+## The Docusaurus Footer Is Disabled
+
+This was done intentionally. The `themeConfig` in `docusaurus.config.js` has **no `footer` key**. This means:
+
+- No Docusaurus footer renders on the landing page (which has its own custom footer)
+- No Docusaurus footer renders on docs pages either
+
+If you want a footer on docs pages, add a `footer` config back to `themeConfig` in `docusaurus.config.js`. But be aware it will show on ALL pages. To hide it on the landing page only, you'd need a CSS rule like:
+
+```css
+html:has(.landingFooter) .footer { display: none; }
+```
+
+Or swizzle the Footer component and conditionally render it.
+
+## Gradient Dividers
+
+Between sections, `index.js` renders `<div className={styles.divider} />`. These are thin horizontal lines with a gradient:
+
+```css
+.divider {
+  max-width: 1200px;
+  margin: 0 auto;
+  height: 1px;
+  background: linear-gradient(90deg, transparent, rgba(168, 85, 247, 0.25), transparent);
+}
+```
+
+## Build & Verify
+
+After any component change:
+
+```bash
+cd website && npm run build
+```
+
+For live preview with hot reload:
+
+```bash
+cd website && npm start
+```
+
+## Static Assets
+
+Landing page images live in `website/static/img/`:
+
+| File | Used by |
+|------|---------|
+| `logo.png` | Navbar, footer |
+| `mascot.png` | Hero section |
+| `screenshots/*.png` | ScreenshotGallery carousel |
+
+To add a new image: place it in `website/static/img/` and reference it as `/img/filename.png` in JSX or CSS.
--- a/.agents/skills/unyo-docs/SKILL.md
+++ b/.agents/skills/unyo-docs/SKILL.md
@@ -0,0 +1,211 @@
+---
+name: unyo-docs
+description: Manage Unyo website documentation — add new pages, update sidebar ordering, edit content using Docusaurus features (admonitions, code blocks, tables, images, internal links). Use this skill whenever the user wants to add, modify, reorder, or reorganize documentation pages, or when they ask about how the docs system works, how to create a new doc, or how to fix broken doc links. Also use it when the user mentions sidebars, frontmatter, or Docusaurus markdown features for the Unyo project.
+---
+
+# Unyo Documentation Guide
+
+This skill covers how to create, modify, and organize documentation pages for the Unyo website (a Docusaurus 3 project).
+
+## Project Context
+
+- **Framework**: Docusaurus 3.10 with `@docusaurus/preset-classic`
+- **Docs directory**: `website/docs/`
+- **Sidebar config**: `website/sidebars.js`
+- **Site config**: `website/docusaurus.config.js`
+- **Blog**: Disabled (no `blog/` directory)
+- **Base URL**: `/docs/` (the intro page uses `slug: /` so it's served at `/docs`, not `/docs/intro`)
+
+## Creating a New Doc Page
+
+### 1. Create the Markdown file
+
+Add a new `.md` file in `website/docs/`:
+
+```bash
+touch website/docs/my-new-page.md
+```
+
+### 2. Add frontmatter
+
+Every doc file **must** have at least a `title` in its YAML frontmatter:
+
+```md
+---
+title: My New Page
+---
+
+# My New Page
+
+Content goes here...
+```
+
+Optional frontmatter fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `title` | string | **required** | Page title shown in sidebar and `<h1>` |
+| `slug` | string | derived from filename | Custom URL path relative to `/docs/` |
+| `sidebar_position` | number | alphabetical | Order in sidebar (only if using `autogenerated` sidebar type) |
+| `description` | string | first line of content | Meta description for SEO |
+| `keywords` | string[] | none | SEO keywords |
+| `hide_table_of_contents` | boolean | `false` | Hide the right-side TOC |
+
+### 3. Add to the sidebar
+
+Edit `website/sidebars.js` and add the filename (without `.md`) in the desired position:
+
+```js
+const sidebars = {
+  docs: [
+    'intro',
+    'installation',
+    'getting-started',
+    'extensions',
+    'my-new-page',  // <-- add here
+  ],
+};
+```
+
+The order in this array determines:
+- The left sidebar navigation order
+- The "Previous" / "Next" links at the bottom of each page
+
+### 4. Verify
+
+```bash
+cd website && npm run build
+```
+
+Check for broken links or missing sidebar entries. A broken sidebar reference will cause a build error.
+
+## URL Structure
+
+- `website/docs/intro.md` has `slug: /` → served at `/docs` (not `/docs/intro`)
+- `website/docs/installation.md` (no slug) → served at `/docs/installation`
+- `website/docs/getting-started.md` (no slug) → served at `/docs/getting-started`
+- `website/docs/extensions.md` (no slug) → served at `/docs/extensions`
+
+**Important**: Because intro.md uses `slug: /`, all links to the intro page should use `/docs` not `/docs/intro`.
+
+### Custom slugs
+
+To change a page's URL, add `slug` to frontmatter:
+
+```md
+---
+slug: /my-custom-url
+title: My Page
+---
+```
+
+This makes the page available at `/docs/my-custom-url`.
+
+## Internal Links
+
+Within docs, use **relative paths** for internal links:
+
+```md
+See the [installation guide](./installation) for setup instructions.
+```
+
+Or absolute paths:
+
+```md
+See the [installation guide](/docs/installation) for setup instructions.
+```
+
+**Never** link to `/docs/intro` — use `/docs` instead (due to `slug: /`).
+
+## Content Features
+
+### Admonitions (callouts)
+
+```md
+:::note
+Informational note
+:::
+
+:::tip
+Helpful suggestion
+:::
+
+:::info
+Important information
+:::
+
+:::caution
+Potential issue warning
+:::
+
+:::danger
+Critical warning
+:::
+```
+
+### Code blocks with syntax highlighting
+
+````md
+```bash
+npm install
+```
+
+```javascript
+const x = 42;
+```
+
+```python
+print("hello")
+```
+````
+
+### Tables
+
+```md
+| Column 1 | Column 2 |
+|----------|----------|
+| Value 1  | Value 2  |
+```
+
+### Images
+
+Place images in `website/static/img/` and reference with absolute paths:
+
+```md
+![Screenshot](/img/screenshots/home.png)
+```
+
+### Tabs
+
+```md
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+  <TabItem value="windows" label="Windows">
+    Windows instructions here
+  </TabItem>
+  <TabItem value="mac" label="macOS">
+    macOS instructions here
+  </TabItem>
+</Tabs>
+```
+
+For MDX tab content, the file must use `.mdx` extension instead of `.md`.
+
+## Editing Existing Docs
+
+1. Edit the `.md` file in `website/docs/`
+2. Run `cd website && npm start` for hot-reload preview
+3. Run `cd website && npm run build` to verify no broken links
+
+## Reordering Docs
+
+Edit the array in `website/sidebars.js`. The order is linear — items appear in the sidebar and previous/next navigation in array order.
+
+## Common Gotchas
+
+1. **`slug: /` on intro.md**: Links to the intro page should use `/docs` not `/docs/intro`.
+2. **Frontmatter is required**: Every doc needs at least `title:` in frontmatter, or Docusaurus will throw a warning and derive the title from the filename.
+3. **Broken sidebar references**: If a filename in `sidebars.js` doesn't match a `.md` file, the build will fail.
+4. **MDX in .md files**: Standard Markdown files (`.md`) support most MDX features but not JSX components. If you need `<Tabs>` or custom components, rename the file to `.mdx`.
--- a/.agents/skills/unyo-theming/SKILL.md
+++ b/.agents/skills/unyo-theming/SKILL.md
@@ -0,0 +1,189 @@
+---
+name: unyo-theming
+description: Customize the Unyo website theme — colors, fonts, backgrounds, component styles, and Docusaurus CSS overrides. Use this skill whenever the user wants to change the visual appearance of the Unyo website, fix CSS issues, override Docusaurus/Infima defaults, or asks about how the theming system works. Also trigger when the user mentions colors looking wrong, backgrounds being grey instead of dark purple, or CSS variables not taking effect.
+---
+
+# Unyo Theming Guide
+
+This skill covers how to customize the visual theme of the Unyo website, including the critical CSS specificity architecture that determines whether overrides actually work.
+
+## CSS Architecture (Read This First)
+
+The theme has two layers that load in this order:
+
+1. **Infima** — Docusaurus's base CSS framework. Ships Docusaurus's default variables and styles.
+2. **Custom CSS** (`website/src/css/custom.css`) — our overrides, loaded after Infima.
+
+This load order means our rules win when specificity is equal. But Infima defines dark-mode variables under `html[data-theme=dark]`, which has specificity `(0, 1, 1)` — higher than `:root`'s `(0, 0, 1)`.
+
+### The #1 Gotcha
+
+**Dark mode overrides MUST go under `html[data-theme=dark]`, NOT under `:root`.**
+
+This is the single most common bug in this project. Infima defines:
+
+```css
+/* infima/default-dark/default-dark.css */
+html[data-theme='dark'] {
+  --ifm-background-color: #1b1b1d;
+  --ifm-background-surface-color: #242526;
+  /* ...more grey defaults */
+}
+```
+
+If you put an override in `:root`:
+
+```css
+:root {
+  --ifm-background-color: #0d0a1a; /* WON'T WORK IN DARK MODE */
+}
+```
+
+`html[data-theme=dark]` has higher specificity than `:root`, so Infima's grey values win. The page will show grey backgrounds on docs pages instead of our dark purple.
+
+The fix is always the same — move the override to `html[data-theme=dark]`:
+
+```css
+html[data-theme=dark] {
+  --ifm-background-color: #0d0a1a; /* NOW WORKS — equal specificity + later source order */
+  --ifm-background-surface-color: #151126;
+}
+```
+
+Since this site is **forced to dark mode** (`colorMode.disableSwitch: true`), this is the only mode that matters.
+
+## Variable Reference
+
+### Custom Unyo Variables (in `:root`)
+
+These are safe to define in `:root` because they don't conflict with Infima:
+
+| Variable | Purpose | Value |
+|----------|---------|-------|
+| `--unyo-bg` | Page background | `#0d0a1a` |
+| `--unyo-bg-surface` | Card/sidebar background | `#151126` |
+| `--unyo-purple` | Primary purple | `#a855f7` |
+| `--unyo-purple-dark` | Darker purple | `#7c3aed` |
+| `--unyo-purple-darker` | Darkest purple | `#5b21b6` |
+| `--unyo-pink` | Accent pink | `#ec4899` |
+| `--unyo-pink-glow` | Soft pink glow | `#f472b6` |
+| `--unyo-text` | Main text color | `#e8e0f0` |
+| `--unyo-text-muted` | Muted text | `#9b8ec4` |
+| `--unyo-gradient` | Standard gradient | `linear-gradient(135deg, #a855f7, #ec4899)` |
+| `--unyo-gradient-hover` | Hover gradient | `linear-gradient(135deg, #7c3aed, #f472b6)` |
+
+### Docusaurus/Infima Overrides (in `html[data-theme=dark]`)
+
+These MUST be in `html[data-theme=dark]` to win over Infima:
+
+| Variable | Purpose | Value |
+|----------|---------|-------|
+| `--ifm-background-color` | Page background | `#0d0a1a` |
+| `--ifm-background-surface-color` | Surface/cards | `#151126` |
+| `--ifm-font-color-base` | Body text | `#e8e0f0` |
+| `--ifm-heading-color` | Headings | `#f5f0ff` |
+| `--ifm-link-color` | Links | `#c084fc` |
+| `--ifm-link-hover-color` | Link hover | `#f472b6` |
+| `--ifm-navbar-background-color` | Navbar bg | `rgba(13, 10, 26, 0.85)` |
+| `--ifm-code-background` | Inline code bg | `#1e1838` |
+| `--ifm-pre-background` | Code block bg | `#1e1838` |
+
+## File Map
+
+Where to change what:
+
+| What you want to change | File | Selector / location |
+|------------------------|------|---------------------|
+| Page background color | `custom.css` | `html[data-theme=dark] { --ifm-background-color }` |
+| Card/sidebar background | `custom.css` | `html[data-theme=dark] { --ifm-background-surface-color }` |
+| Link colors | `custom.css` | `html[data-theme=dark] { --ifm-link-color, --ifm-link-hover-color }` |
+| Navbar blur/transparency | `custom.css` | `.navbar { backdrop-filter }` section |
+| Navbar title gradient | `custom.css` | `.navbar__title { background, -webkit-background-clip }` |
+| Sidebar background | `custom.css` | `.theme-doc-sidebar-container { background-color }` |
+| Docs headings gradient | `custom.css` | `.theme-doc-markdown h1 { background }` |
+| Docs code blocks | `custom.css` | `.theme-doc-markdown code { background, border, color }` |
+| Pagination buttons | `custom.css` | `.pagination-nav__link { border, background, color }` |
+| Landing page sections | `src/pages/index.module.css` | `.main`, `.landingFooter`, `.divider` |
+| Hero section | `src/components/Hero/styles.module.css` | All hero styles |
+| Feature cards | `src/components/FeatureGrid/styles.module.css` | All grid styles |
+| Screenshot carousel | `src/components/ScreenshotGallery/styles.module.css` | All gallery styles |
+
+## CSS Modules
+
+The landing page components use **CSS Modules** (`.module.css` files). These provide scoped class names — the class `heroTitle` in `Hero/styles.module.css` becomes something like `heroTitle_x4aB` in the output, preventing style collisions.
+
+When importing in a component:
+
+```js
+import styles from './styles.module.css';
+// Use as: className={styles.heroTitle}
+```
+
+Global styles (like Docusaurus class names like `.navbar`, `.menu__link`) are in `custom.css` without modules.
+
+## Adding a New Color
+
+1. Define the variable in `custom.css` under `:root`:
+
+```css
+:root {
+  --unyo-orange: #f97316;
+}
+```
+
+2. Use it anywhere:
+
+```css
+.my-element {
+  color: var(--unyo-orange);
+}
+```
+
+If you need to override an `--ifm-*` variable, add it under `html[data-theme=dark]` instead.
+
+## Changing a Docusaurus Infira Override
+
+1. Find the variable in `html[data-theme=dark]` block in `custom.css`
+2. Change the value
+3. Build and verify: `cd website && npm run build`
+
+**Never** put `--ifm-*` overrides in `:root` — they will be silently overridden by Infima's `html[data-theme=dark]` block.
+
+## Fonts
+
+Fonts are loaded via Google Fonts import at the top of `custom.css`:
+
+```css
+@import url('https://fonts.googleapis.com/css2?family=Outfit:wght@300;400;500;600;700;800;900&family=IBM+Plex+Sans:wght@300;400;500;600;700&display=swap');
+```
+
+- **Outfit** — used for headings (`--ifm-font-family-heading`)
+- **IBM Plex Sans** — used for body text (`--ifm-font-family-base`)
+
+Both are defined in `custom.css` under `:root`.
+
+## Build & Verify
+
+After any CSS change:
+
+```bash
+cd website && npm run build
+```
+
+For live preview during development:
+
+```bash
+cd website && npm start
+```
+
+## Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Grey backgrounds on docs pages | `--ifm-background-color` in `:root` instead of `html[data-theme=dark]` | Move the override to `html[data-theme=dark]` |
+| Links are default blue | `--ifm-link-color` in `:root` being overridden | Move to `html[data-theme=dark]` |
+| Code blocks look wrong | `--ifm-code-background` overridden by Infima's dark theme | Move to `html[data-theme=dark]` |
+| Sidebar has wrong background | `--ifm-background-surface-color` in `:root` | Move to `html[data-theme=dark]` |
+| Color change has no visible effect | Variable overridden by more specific selector | Check if it's an Infima dark theme variable — move to `html[data-theme=dark]` |
+
+**The rule of thumb**: if the variable starts with `--ifm-`, it almost certainly needs to go under `html[data-theme=dark]`. Custom `--unyo-*` variables are safe in `:root`.
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,310 @@
+# Contributing to Unyo Website
+
+Thanks for your interest in contributing! This guide covers how the project works, how to set up your environment, and how to make changes.
+
+## How the Project Works
+
+### Architecture
+
+The site is a **Docusaurus 3** application — a React-based static site generator. It produces two types of pages:
+
+1. **Landing page** (`/`) — a custom React page at `website/src/pages/index.js` with hand-written components (Hero, FeatureGrid, ScreenshotGallery) and a custom footer
+2. **Documentation pages** (`/docs/*`) — Markdown files in `website/docs/` rendered by Docusaurus with a sidebar
+
+Docusaurus provides:
+- The navbar (top bar with logo, "Docs" link, "GitHub" link)
+- The docs sidebar and previous/next navigation
+- Markdown rendering with MDX support
+- Static site generation via `npm run build`
+
+The theme is **forced dark mode** (no toggle). All color customization lives in `website/src/css/custom.css`.
+
+### Build Pipeline
+
+```
+Markdown (.md) + React components (.js)
+         ↓
+    Docusaurus (Webpack 5)
+         ↓
+    Static HTML/CSS/JS (website/build/)
+         ↓
+    Docker (Node 20 build → Nginx Alpine serve)
+         ↓
+    Production (port 80)
+```
+
+### Key Files
+
+| File | What it controls |
+|------|-----------------|
+| `website/docusaurus.config.js` | Site metadata, navbar, theme config, presets |
+| `website/sidebars.js` | Documentation sidebar order |
+| `website/src/css/custom.css` | All theme colors and global styles |
+| `website/src/pages/index.js` | Landing page composition |
+| `website/src/components/*/` | React components for the landing page |
+| `website/docs/*.md` | Documentation content |
+
+### CSS Architecture
+
+There are two layers of styling:
+
+1. **Infima** — Docusaurus's base CSS framework (ships with `@docusaurus/preset-classic`). Defines variables like `--ifm-background-color`, `--ifm-color-primary`, etc. under `:root` and `html[data-theme=dark]`.
+
+2. **custom.css** — our overrides. Defines Unyo variables (`--unyo-*`) and overrides Infima variables (`--ifm-*`).
+
+**Important**: Dark mode overrides must be in `html[data-theme=dark]` to match Infima's specificity. Rules in `:root` will be overridden by Infima's `html[data-theme=dark]` block since that selector has higher specificity than `:root`.
+
+Component styles use **CSS Modules** (`.module.css` files) for scoped class names — no global pollution.
+
+### Landing Page vs Docs
+
+- The **landing page** does **not** use the Docusaurus footer. It has its own `<footer>` element in `index.js` styled by `index.module.css`. The Docusaurus footer is disabled by removing `footer` from `themeConfig` in `docusaurus.config.js`.
+- The **docs pages** use the Docusaurus sidebar, breadcrumbs, and pagination — styled by the global `custom.css`.
+
+## Setup
+
+```bash
+# Clone the repo
+git clone https://github.com/K3vinb5/Unyo.git
+cd unyo-page/website
+
+# Install dependencies
+npm install
+
+# Start dev server
+npm start
+```
+
+The dev server runs at `http://localhost:3000` with hot reloading.
+
+## Adding New Documentation
+
+### Step-by-step
+
+#### 1. Create the Markdown file
+
+Add a new `.md` file in `website/docs/`:
+
+```bash
+touch website/docs/my-topic.md
+```
+
+#### 2. Add frontmatter
+
+Every doc file **must** have a `title` in its YAML frontmatter. Optionally add `slug` to customize the URL:
+
+```md
+---
+title: My Topic
+slug: /custom-url
+---
+
+# My Topic
+
+Your content here...
+```
+
+Without a `slug`, the URL will be `/docs/my-topic` (derived from the filename).
+
+#### 3. Add to the sidebar
+
+Open `website/sidebars.js` and add the filename (without `.md`) in the position you want it to appear:
+
+```js
+const sidebars = {
+  docs: [
+    'intro',
+    'installation',
+    'getting-started',
+    'extensions',
+    'my-topic',       // <-- add here
+  ],
+};
+```
+
+The order in this array determines:
+- The sidebar navigation order
+- The "Previous" / "Next" links at the bottom of each doc page
+
+#### 4. Create content
+
+Docusaurus supports standard Markdown plus MDX (Markdown with JSX). Some features:
+
+**Admonitions** (callouts):
+```md
+:::tip
+Helpful tip here
+:::
+
+:::info
+Informational note
+:::
+
+:::caution
+Warning about potential issues
+:::
+```
+
+**Code blocks with syntax highlighting**:
+````md
+```bash
+npm install
+```
+````
+
+**Tables**:
+```md
+| Column 1 | Column 2 |
+|----------|----------|
+| Value 1  | Value 2  |
+```
+
+**Internal links** — use relative paths within docs:
+```md
+See the [installation guide](./installation) for setup instructions.
+```
+
+**External links** — use full URLs:
+```md
+Check the [Unyo repo](https://github.com/K3vinb5/Unyo) for source code.
+```
+
+**Images** — place in `website/static/img/` and reference with absolute paths:
+```md
+![Screenshot](/img/screenshots/home.png)
+```
+
+#### 5. Verify
+
+```bash
+cd website
+npm start
+# Navigate to http://localhost:3000/docs/my-topic
+```
+
+## Modifying the Landing Page
+
+### Hero Section
+
+Files: `website/src/components/Hero/index.js` and `styles.module.css`
+
+- **Mascot image**: `website/static/img/mascot.png`
+- **CTA buttons**: "Get Started" links to `/docs`, "GitHub" links to the repo
+- **Animations**: CSS keyframes for fade-in, slide-up, floating mascot
+
+### Feature Grid
+
+Files: `website/src/components/FeatureGrid/index.js` and `styles.module.css`
+
+- Features are defined as a JS array of objects (`title`, `description`, `icon`)
+- Icons are inline SVGs — edit them directly in the component
+- Cards use staggered animation on intersection (CSS `animation-delay`)
+
+### Screenshot Gallery
+
+Files: `website/src/components/ScreenshotGallery/index.js` and `styles.module.css`
+
+- Screenshots array is defined in the component
+- Add/remove by editing the `screenshots` array
+- The center slide scales to full size (`scale(1)`) while side slides are dimmed (`0.88` scale, `0.65` opacity)
+- Clicking opens a lightbox
+
+### Custom Footer
+
+The landing page footer is defined directly in `website/src/pages/index.js` (not using Docusaurus's footer system). Styles are in `website/src/pages/index.module.css`.
+
+## Modifying the Theme
+
+All color changes go in `website/src/css/custom.css`. The file is organized into sections:
+
+1. **CSS Variables** (`:root` and `html[data-theme=dark]`) — all color definitions
+2. **Global styles** — `html`, `body`, `::selection`
+3. **Navbar** — `.navbar`, `.navbar__title`, `.navbar__link`
+4. **Sidebar** — `.theme-doc-sidebar-container`, `.menu__link`
+5. **Docs pages** — `.theme-doc-markdown` (headings, links, code, tables, blockquotes)
+6. **Breadcrumb** — `.breadcrumbs__link`
+7. **Pagination** — `.pagination-nav__link`
+8. **Search** — `.DocSearch-Button`
+9. **Mobile menu** — `.menu--show`
+
+### Adding a New Color Variable
+
+1. Add it to `:root` with the `--unyo-` prefix:
+   ```css
+   :root {
+     --unyo-new-color: #ff6600;
+   }
+   ```
+
+2. Use it anywhere:
+   ```css
+   .my-element {
+     color: var(--unyo-new-color);
+   }
+   ```
+
+### Overriding an Infima Variable
+
+Infima variables must be overridden in the `html[data-theme=dark]` block — **not** in `:root`. This is because Infima defines its dark theme under `html[data-theme=dark]`, which has higher specificity than `:root`.
+
+```css
+html[data-theme=dark] {
+  --ifm-background-color: #0d0a1a;  /* overrides Infima's #1b1b1d */
+}
+```
+
+## Building and Deploying
+
+### Local Build
+
+```bash
+cd website
+npm run build
+```
+
+The static site is output to `website/build/`.
+
+### Docker Build
+
+```bash
+docker compose up --build
+```
+
+This runs the full multi-stage build:
+1. Node 20 Alpine installs deps and builds the Docusaurus site
+2. Nginx Alpine serves the static files
+
+The container exposes port 80 by default.
+
+### Changing the Domain
+
+Edit `website/docusaurus.config.js`:
+
+```js
+url: 'https://your-domain.com',
+```
+
+Then rebuild.
+
+## Common Tasks
+
+| Task | How |
+|------|-----|
+| Add a new doc page | Create `.md` file in `website/docs/`, add to `sidebars.js` |
+| Reorder docs sidebar | Edit the array in `website/sidebars.js` |
+| Change navbar items | Edit `themeConfig.navbar` in `docusaurus.config.js` |
+| Change theme colors | Edit variables in `website/src/css/custom.css` |
+| Add a screenshot | Put image in `website/static/img/`, reference as `/img/filename.png` |
+| Update the mascot | Replace `website/static/img/mascot.png` |
+| Update the logo | Replace `website/static/img/logo.png` (also referenced in `docusaurus.config.js`) |
+| Run dev server | `cd website && npm start` |
+| Production build | `cd website && npm run build` |
+| Docker deploy | `docker compose up -d --build` |
+
+## Gotchas
+
+- **Webpack compatibility**: The project pins `webpack@^5.99.0` in `package.json` because newer versions (5.106+) break Docusaurus's webpackbar ProgressPlugin. Do not upgrade webpack without testing the build.
+- **Dark mode only**: The `colorMode.disableSwitch: true` config removes the theme toggle. All CSS variables must work in dark mode.
+- **Footer is disabled**: The Docusaurus default footer (`themeConfig.footer`) is intentionally removed. The landing page has its own footer. If you want a footer on docs pages, add `footer` back to `themeConfig` and style it in `custom.css`.
+- **`html[data-theme=dark]` specificity**: Infima dark theme overrides must go under `html[data-theme=dark]` in `custom.css`, not `:root`. Otherwise Infima's dark variables will win.
+- **`slug: /` on intro.md**: The intro doc uses `slug: /` which makes it accessible at `/docs/` instead of `/docs/intro`. Links to it should use `/docs` not `/docs/intro`.
--- a/README.md
+++ b/README.md
@@ -0,0 +1,238 @@
+# Unyo Website
+
+Landing page and documentation website for [Unyo](https://github.com/K3vinb5/Unyo) — a simple anime streaming and manga reading desktop app.
+
+## Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | [Docusaurus 3](https://docusaurus.io/) (React-based static site generator) |
+| UI | React 18, CSS Modules |
+| Styling | Custom dark purple/pink theme (Infima + custom CSS overrides) |
+| Build | Webpack 5 (via Docusaurus) |
+| Server | Nginx (Alpine) via Docker |
+| Container | Multi-stage Dockerfile (Node 20 build → Nginx serve) |
+
+## Project Structure
+
+```
+unyo-page/
+├── assets/                    # Original screenshots and mascot (not used directly)
+├── docker/
+│   ├── Dockerfile             # Multi-stage: Node build → Nginx serve
+│   └── nginx.conf             # Nginx config with SPA fallback and gzip
+├── docker-compose.yml         # Production deployment config
+├── .dockerignore
+├── website/                   # Docusaurus project
+│   ├── package.json
+│   ├── babel.config.js
+│   ├── docusaurus.config.js   # Site config (navbar, theme, presets)
+│   ├── sidebars.js            # Docs sidebar ordering
+│   ├── static/img/            # Static assets (logos, screenshots, mascot)
+│   ├── src/
+│   │   ├── css/
+│   │   │   └── custom.css     # Purple/pink anime theme (all CSS variables)
+│   │   ├── pages/
+│   │   │   ├── index.js       # Landing page
+│   │   │   └── index.module.css
+│   │   └── components/
+│   │       ├── Hero/           # Hero section with mascot + CTAs
+│   │       ├── FeatureGrid/    # 6-card feature grid
+│   │       └── ScreenshotGallery/ # Horizontal carousel with lightbox
+│   └── docs/                  # Documentation markdown files
+│       ├── intro.md
+│       ├── installation.md
+│       ├── getting-started.md
+│       └── extensions.md
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- npm 10+
+
+### Install Dependencies
+
+```bash
+cd website
+npm install
+```
+
+### Development Server
+
+```bash
+cd website
+npm start
+```
+
+Opens at `http://localhost:3000`. Hot-reloading is enabled.
+
+### Production Build
+
+```bash
+cd website
+npm run build
+```
+
+Output goes to `website/build/`. Serve locally with `npm run serve`.
+
+### Docker
+
+Build and run the containerized site:
+
+```bash
+docker compose up --build
+```
+
+Serves at `http://localhost:80`.
+
+To run in the background:
+
+```bash
+docker compose up -d --build
+```
+
+To stop:
+
+```bash
+docker compose down
+```
+
+### Custom Port
+
+Edit `docker-compose.yml` and change the ports mapping, e.g. `"8080:80"` for port 8080.
+
+## Deployment
+
+1. Build the Docker image: `docker compose build`
+2. Push to your VPS or use `docker save` / `docker load`
+3. Run with `docker compose up -d`
+4. Configure your reverse proxy (e.g. Caddy, Traefik) to forward to port 80
+
+### Configuration
+
+Before deploying, update `docusaurus.config.js`:
+
+- `url` — your production domain (currently `https://unyo.dev`)
+- `baseUrl` — subpath if not deploying at root (currently `/`)
+
+### Static Build (No Docker)
+
+```bash
+cd website
+npm run build
+# Serve the build/ directory with any static file server
+npx serve build
+```
+
+## Adding Documentation
+
+Documentation lives in `website/docs/` as Markdown files.
+
+### 1. Create a new Markdown file
+
+```bash
+touch website/docs/my-new-page.md
+```
+
+### 2. Add frontmatter
+
+Every doc needs a `title` in its frontmatter:
+
+```md
+---
+title: My New Page
+---
+
+# My New Page
+
+Content goes here...
+```
+
+### 3. Add it to the sidebar
+
+Edit `website/sidebars.js` and add the filename (without `.md`) to the `docs` array:
+
+```js
+const sidebars = {
+  docs: [
+    'intro',
+    'installation',
+    'getting-started',
+    'extensions',
+    'my-new-page',  // <-- add here
+  ],
+};
+```
+
+The order in this array determines the sidebar and previous/next navigation order.
+
+### 4. Link to it from other pages
+
+Use relative paths for internal links:
+
+```md
+Check out [the new page](./my-new-page) for details.
+```
+
+Or absolute paths:
+
+```md
+Check out [the new page](/docs/my-new-page) for details.
+```
+
+### Using `slug` for custom URLs
+
+By default, a file at `docs/my-new-page.md` is served at `/docs/my-new-page`. To change the URL, add a `slug` in frontmatter:
+
+```md
+---
+slug: /my-custom-url
+title: My New Page
+---
+```
+
+This makes the page available at `/docs/my-custom-url` instead.
+
+### Images
+
+Place images in `website/static/img/` and reference them with absolute paths:
+
+```md
+![Alt text](/img/my-image.png)
+```
+
+## Modifying the Theme
+
+All theme customization lives in `website/src/css/custom.css`. The file uses CSS custom properties (variables) defined in two blocks:
+
+- `:root` — custom Unyo variables (`--unyo-*`)
+- `html[data-theme=dark]` — Docusaurus Infima overrides (`--ifm-*`)
+
+The `html[data-theme=dark]` selector is required because Infima's default dark theme uses the same selector, and we need equal specificity for our overrides to take effect.
+
+### Key Variables
+
+| Variable | Purpose | Value |
+|----------|---------|-------|
+| `--unyo-bg` | Page background | `#0d0a1a` |
+| `--unyo-bg-surface` | Card/sidebar background | `#151126` |
+| `--unyo-purple` | Primary purple | `#a855f7` |
+| `--unyo-pink` | Accent pink | `#ec4899` |
+| `--unyo-text` | Main text | `#e8e0f0` |
+| `--unyo-text-muted` | Muted text | `#9b8ec4` |
+
+## Landing Page Components
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| `Hero` | `src/components/Hero/` | Mascot, tagline, CTAs |
+| `FeatureGrid` | `src/components/FeatureGrid/` | 6 feature cards with icons |
+| `ScreenshotGallery` | `src/components/ScreenshotGallery/` | Horizontal scroll carousel + lightbox |
+| Custom footer | `src/pages/index.js` | Inline footer (not Docusaurus default) |
+
+## License
+
+This website is part of the Unyo project. See the [Unyo repository](https://github.com/K3vinb5/Unyo) for license information.