astro-docker-kit/README.md

<div align="center">

# 🚀 Astro Docker Kit

</div>

## 🚀 Quick Start

```bash
git clone https://github.com/advento-ir/astro-docker-kit
cd astro-docker-kit
npm install
npm run dev
```

Visit `http://localhost:4321`.

---

## 🐳 Deploy with Docker

```bash
cp .env.example .env
docker network create private-net   # required once
docker compose up -d
```

---

## 📁 Project Structure

```text
/
├── public/fonts/iran-yekan-x/     # IRANYekanX woff2 files
├── src/
│   ├── components/
│   │   ├── blocks/                # Content block components
│   │   ├── core/                  # Base UI components
│   │   ├── layout/                # Header, footer, sidebar
│   │   └── meta/SEO.astro         # SEO component
│   ├── layouts/BaseLayout.astro   # RTL/FA base layout
│   ├── pages/index.astro          # Homepage
│   └── styles/
│       ├── fonts.css              # Persian font definitions
│       └── global.css             # Global styles + Tailwind
├── Dockerfile
├── docker-compose.yml
└── nginx.conf
```

---

## 🔍 SEO Component

`src/components/meta/SEO.astro` is a full-featured, drop-in SEO component used inside `BaseLayout.astro`. It handles every layer of modern SEO — from core meta tags to structured data — with zero external dependencies.

### Features at a glance

| Category | What's included |
| --- | --- |
| Core meta | `<title>`, `description`, `keywords`, `author`, `robots`, `theme-color`, `color-scheme`, `generator` |
| Canonical | Auto-detected from `Astro.url.href` or manually overridden |
| Open Graph | `og:type`, `og:title`, `og:description`, `og:image` (+ width/height/alt), `og:locale`, `og:site_name` |
| OG Article | `article:published_time`, `article:modified_time`, `article:section`, `article:tag`, `article:author` |
| Twitter Card | `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`, `twitter:site`, `twitter:creator` |
| JSON-LD | Auto-generated `WebSite`, `WebPage` / `Article`, `BreadcrumbList` schemas + custom schema injection |
| hreflang | Alternate locale `<link>` tags for multilingual sites |
| Resource hints | `preconnect` and `dns-prefetch` link tags |
| Favicon | SVG icon, ICO fallback, Apple touch icon, Web App Manifest |

---

### Basic usage

`BaseLayout.astro` already wires the component up — just pass props when using the layout:

```astro
---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout
  title="My Page"
  description="A short description of this page."
/>
```

All other props are optional and tree-shake to nothing when unused.

---

### All props

#### Core

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `title` | `string` | **required** | Page title (also used as OG/Twitter fallback) |
| `titleTemplate` | `string` | `'%s'` | Wraps the title — `%s` is replaced with `title`. E.g. `'%s \| Advento'` |
| `description` | `string` | **required** | Meta description (also used as OG/Twitter fallback) |
| `keywords` | `string[]` | — | Comma-joined into `<meta name="keywords">` |
| `author` | `string` | — | `<meta name="author">` |
| `themeColor` | `string` | `'#7c3aed'` | `<meta name="theme-color">` |

#### Canonical & Robots

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `canonical` | `string` | `Astro.url.href` | Absolute canonical URL |
| `noindex` | `boolean` | `false` | Add `noindex` to the robots directive |
| `nofollow` | `boolean` | `false` | Add `nofollow` to the robots directive |

#### Open Graph

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ogType` | `'website' \| 'article' \| 'profile'` | `'website'` | OG object type |
| `ogTitle` | `string` | resolved `title` | Override OG title |
| `ogDescription` | `string` | `description` | Override OG description |
| `ogImage` | `string` | — | Absolute URL to the OG image (1200×630 recommended) |
| `ogImageAlt` | `string` | — | Alt text for the OG image |
| `ogImageWidth` | `number` | `1200` | OG image width in pixels |
| `ogImageHeight` | `number` | `630` | OG image height in pixels |
| `ogLocale` | `string` | `'fa_IR'` | OG locale string |
| `ogSiteName` | `string` | — | `og:site_name` |

#### Twitter Card

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `twitterCard` | `'summary' \| 'summary_large_image' \| 'app' \| 'player'` | `'summary_large_image'` | Card type |
| `twitterSite` | `string` | — | Site Twitter handle (e.g. `@advento_ir`) |
| `twitterCreator` | `string` | — | Author Twitter handle |
| `twitterTitle` | `string` | OG title | Override Twitter title |
| `twitterDescription` | `string` | OG description | Override Twitter description |
| `twitterImage` | `string` | OG image | Override Twitter image URL |
| `twitterImageAlt` | `string` | — | Alt text for the Twitter image |

#### Article (requires `ogType="article"`)

Pass an `article` object with the following shape:

```ts
interface ArticleMeta {
  publishedTime: string;   // ISO 8601, e.g. "2025-01-15T10:00:00Z"
  modifiedTime?: string;
  authors?: string[];      // names or profile URLs
  section?: string;
  tags?: string[];
}
```

#### JSON-LD & Breadcrumbs

| Prop | Type | Description |
| --- | --- | --- |
| `breadcrumbs` | `BreadcrumbItem[]` | Generates a `BreadcrumbList` schema automatically |
| `jsonLd` | `Record<string, unknown> \| Record<string, unknown>[]` | Inject one or more custom schema.org objects |

```ts
interface BreadcrumbItem {
  name: string;
  url: string;  // absolute URL
}
```

#### Alternates & Resource Hints

| Prop | Type | Description |
| --- | --- | --- |
| `alternateLocales` | `AlternateLocale[]` | Emits `<link rel="alternate" hreflang="...">` for each entry |
| `preconnect` | `string[]` | Emits `<link rel="preconnect">` for each origin |
| `dnsPrefetch` | `string[]` | Emits `<link rel="dns-prefetch">` for each origin |

```ts
interface AlternateLocale {
  hreflang: string;  // e.g. "en", "fa", "x-default"
  href: string;      // absolute URL
}
```

#### Favicon & Manifest

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `faviconSvg` | `string` | `'/favicon.svg'` | Path to SVG favicon |
| `faviconIco` | `string` | — | Path to `.ico` favicon (legacy browsers) |
| `appleTouchIcon` | `string` | — | Path to Apple touch icon (180×180 PNG) |
| `manifestHref` | `string` | — | Path to `manifest.json` / `manifest.webmanifest` |

---

### Full example — article page

```astro
---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout
  title="How We Built This Kit"
  titleTemplate="%s | Advento"
  description="A deep-dive into our Astro + Docker starter setup."
  keywords={['Astro', 'Docker', 'Tailwind', 'RTL']}
  author="Advento Team"
  canonical="https://advento.ir/blog/how-we-built-this-kit"
  ogType="article"
  ogImage="https://advento.ir/og/how-we-built-this-kit.png"
  ogImageAlt="Screenshot of the Astro Docker Kit starter"
  ogSiteName="Advento"
  twitterSite="@advento_ir"
  twitterCreator="@advento_ir"
  article={{
    publishedTime: '2025-01-15T10:00:00Z',
    modifiedTime: '2025-06-01T08:00:00Z',
    authors: ['Advento Team'],
    section: 'Engineering',
    tags: ['Astro', 'Docker', 'SEO'],
  }}
  breadcrumbs={[
    { name: 'Home', url: 'https://advento.ir' },
    { name: 'Blog', url: 'https://advento.ir/blog' },
    { name: 'How We Built This Kit', url: 'https://advento.ir/blog/how-we-built-this-kit' },
  ]}
  alternateLocales={[
    { hreflang: 'fa', href: 'https://advento.ir/fa/blog/how-we-built-this-kit' },
    { hreflang: 'x-default', href: 'https://advento.ir/blog/how-we-built-this-kit' },
  ]}
  preconnect={['https://fonts.gstatic.com']}
/>
```

---

## 🧞 Commands

| Command                | Action                               |
| ---------------------- | ------------------------------------ |
| `npm run dev`          | Start dev server at `localhost:4321` |
| `npm run build`        | Build production site to `./dist/`   |
| `npm run preview`      | Preview the production build locally |
| `npm run format`       | Format code with Prettier            |
| `npm run lint`         | Lint with ESLint                     |
| `docker compose up -d` | Run container in background          |

---

## 🤝 Contributing

1. Fork the repo
2. Create a branch: `git checkout -b feature/your-feature`
3. Commit: `git commit -m 'feat: add your feature'`
4. Push and open a Pull Request

---

## 🌌 About Advento

At [Advento](https://advento.ir), we are redefining the digital marketing landscape. By harnessing the absolute edge of Artificial Intelligence, we deliver highly scalable, data-driven, and innovative solutions. This repository is part of our commitment to pushing the boundaries of what's possible in digital marketing technology.

---

## 📄 License

MIT — see [LICENSE](LICENSE) for details.

---

<div align="center">

Made with ❤️ by [**Advento**](https://advento.ir)

</div>