# shipyard

> shipyard is an Astro-based page builder for creating documentation sites, blogs, and content-focused websites with responsive design, i18n support, and modular components.

shipyard provides three packages: @levino/shipyard-base (core layouts and configuration), @levino/shipyard-docs (documentation features with sidebar and pagination), and @levino/shipyard-blog (blog functionality). It uses Tailwind CSS 4 with DaisyUI 5 for styling.

## Complete Setup (all steps required)

### Step 1: Install packages

Full-featured site (docs + blog):
```bash
npm install @levino/shipyard-base @levino/shipyard-docs @levino/shipyard-blog tailwindcss @tailwindcss/vite daisyui @tailwindcss/typography
```

Documentation site only (no blog):
```bash
npm install @levino/shipyard-base @levino/shipyard-docs tailwindcss @tailwindcss/vite daisyui @tailwindcss/typography
```

### Step 2: Create src/styles/app.css

This file is required. Every `@import` shown below is needed — each shipyard package ships its own `@source` directives that tell Tailwind where to scan for classes. Missing an import causes partially unstyled components.

Full-featured site (docs + blog):
```css
@import "tailwindcss";
@import "@levino/shipyard-base";
@import "@levino/shipyard-blog";
@import "@levino/shipyard-docs";
@plugin "daisyui";
@plugin "@tailwindcss/typography";
```

Documentation site only (no blog — omit the blog import):
```css
@import "tailwindcss";
@import "@levino/shipyard-base";
@import "@levino/shipyard-docs";
@plugin "daisyui";
@plugin "@tailwindcss/typography";
```

### Step 3: Configure astro.config.mjs

The `?url` import and `css: appCss` parameter are both required — without them, styles will not be applied.

Full-featured site:
```javascript
import shipyard from '@levino/shipyard-base'
import shipyardDocs from '@levino/shipyard-docs'
import shipyardBlog from '@levino/shipyard-blog'
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'astro/config'
import appCss from './src/styles/app.css?url'

export default defineConfig({
  vite: { plugins: [tailwindcss()] },
  integrations: [
    shipyard({
      css: appCss,
      brand: 'My Site',
      title: 'My Site',
      tagline: 'Built with shipyard',
      navigation: {
        docs: { label: 'Docs', href: '/docs' },
        blog: { label: 'Blog', href: '/blog' },
      },
    }),
    shipyardDocs(),
    shipyardBlog(),
  ],
})
```

Documentation site only:
```javascript
import shipyard from '@levino/shipyard-base'
import shipyardDocs from '@levino/shipyard-docs'
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'astro/config'
import appCss from './src/styles/app.css?url'

export default defineConfig({
  vite: { plugins: [tailwindcss()] },
  integrations: [
    shipyard({
      css: appCss,
      brand: 'My Site',
      title: 'My Site',
      tagline: 'Built with shipyard',
      navigation: {
        docs: { label: 'Docs', href: '/docs' },
      },
    }),
    shipyardDocs(),
  ],
})
```

### Step 4: Configure src/content.config.ts (Astro 5+)

This file is essential. Without it you get "The collection does not exist" errors.

Full-featured site:
```typescript
import { defineCollection } from 'astro:content'
import { createDocsCollection } from '@levino/shipyard-docs'
import { blogSchema } from '@levino/shipyard-blog'
import { glob } from 'astro/loaders'

const docs = defineCollection(createDocsCollection('./docs'))
const blog = defineCollection({
  schema: blogSchema,
  loader: glob({ pattern: '**/*.md', base: './blog' }),
})
export const collections = { docs, blog }
```

Documentation site only:
```typescript
import { defineCollection } from 'astro:content'
import { createDocsCollection } from '@levino/shipyard-docs'

const docs = defineCollection(createDocsCollection('./docs'))
export const collections = { docs }
```

### Step 5: Create content

Create docs/index.md:
```yaml
---
title: Getting Started
sidebar:
  position: 1
description: Introduction to my project
---
```

## Common Mistakes

- **Missing `css: appCss` or `?url` import**: Components render but are completely unstyled.
- **Missing a shipyard CSS import**: Components from the missing package are partially unstyled because Tailwind doesn't scan that package's classes.
- **Missing `src/content.config.ts`**: Build fails with "The collection does not exist".

## Key Documentation Pages

- [Getting Started](/en/docs/getting-started) - Full setup guide with troubleshooting
- [Tailwind CSS Setup](/en/docs/guides/tailwind-setup) - Detailed CSS configuration and migration guide
- [Base Package](/en/docs/base-package) - Layouts, navigation, and configuration
- [Docs Package](/en/docs/docs-package) - Sidebar, pagination, and frontmatter options
- [Blog Package](/en/docs/blog-package) - Blog functionality and customization
- [Server Mode](/en/docs/server-mode) - Server-side rendering with auth middleware

## Documentation

- [Code Style Guide](https://shipyard.levinkeller.de/docs/_llms-txt/contributing/code-style.txt): Coding conventions for shipyard contributors
- [Comparison with Other Tools](https://shipyard.levinkeller.de/docs/_llms-txt/why-shipyard/comparison.txt)
- [Tailwind CSS Setup](https://shipyard.levinkeller.de/docs/_llms-txt/guides/tailwind-setup.txt): Configure Tailwind CSS 4 with shipyard
- [Functional Programming](https://shipyard.levinkeller.de/docs/_llms-txt/contributing/code-style/functional-programming.txt): Functional programming conventions for shipyard
- [Getting Started](https://shipyard.levinkeller.de/docs/_llms-txt/getting-started.txt): Learn how to install and configure shipyard for your Astro project
- [The shipyard Philosophy](https://shipyard.levinkeller.de/docs/_llms-txt/why-shipyard/philosophy.txt)
- [@levino/shipyard-base](https://shipyard.levinkeller.de/docs/_llms-txt/base-package.txt): Core package providing layouts and configuration for shipyard
- [Naming Conventions](https://shipyard.levinkeller.de/docs/_llms-txt/contributing/code-style/naming-conventions.txt): Naming conventions for shipyard
- [Sustainability & Production Readiness](https://shipyard.levinkeller.de/docs/_llms-txt/why-shipyard/sustainability.txt)
- [@levino/shipyard-docs](https://shipyard.levinkeller.de/docs/_llms-txt/docs-package.txt): Documentation plugin for shipyard with automatic sidebar and pagination
- [Documentation Through Code](https://shipyard.levinkeller.de/docs/_llms-txt/contributing/code-style/documentation-through-code.txt): Let code document itself through clear names and types
- [Markdown Features](https://shipyard.levinkeller.de/docs/_llms-txt/guides/markdown-features.txt): Learn about admonitions, code blocks, tabs, and other enhanced markdown features in shipyard
- [@levino/shipyard-blog](https://shipyard.levinkeller.de/docs/_llms-txt/blog-package.txt): Blog plugin for shipyard with pagination and sidebar
- [Announcement Bar](https://shipyard.levinkeller.de/docs/_llms-txt/guides/announcement-bar.txt): Add a dismissible announcement banner to the top of your site
- [Web Components and Native APIs](https://shipyard.levinkeller.de/docs/_llms-txt/contributing/code-style/web-components.txt): Use custom elements instead of frameworks for interactivity
- [Blog Authors & Tags](https://shipyard.levinkeller.de/docs/_llms-txt/guides/blog-authors-tags.txt): Configure blog authors and tags with dedicated pages and feeds
- [Server Mode (SSR)](https://shipyard.levinkeller.de/docs/_llms-txt/server-mode.txt): Learn how to use shipyard with Astro's server-side rendering (SSR) mode
- [Docusaurus Feature Parity Roadmap](https://shipyard.levinkeller.de/docs/_llms-txt/roadmap.txt): Detailed roadmap showing Docusaurus features that shipyard supports or plans to support
- [Basic Versioning](https://shipyard.levinkeller.de/docs/_llms-txt/examples/basic-versioning.txt): Minimal setup for versioned documentation
- [Contributing](https://shipyard.levinkeller.de/docs/_llms-txt/contributing.txt)
- [Documentation Versioning](https://shipyard.levinkeller.de/docs/_llms-txt/guides/versioning.txt): Learn how to create versioned documentation with shipyard
- [Examples](https://shipyard.levinkeller.de/docs/_llms-txt/examples.txt): Copy-paste examples for common shipyard configurations
- [Guides](https://shipyard.levinkeller.de/docs/_llms-txt/guides.txt): In-depth guides for shipyard features
- [Migrating to Versioned Docs](https://shipyard.levinkeller.de/docs/_llms-txt/guides/migration-to-versioned.txt): Step-by-step guide for migrating existing documentation to versioned docs
- [shipyard Documentation](https://shipyard.levinkeller.de/docs/_llms-txt/en.txt)
- [Version Lifecycle](https://shipyard.levinkeller.de/docs/_llms-txt/examples/version-lifecycle.txt): Managing the complete lifecycle of documentation versions
- [Versioning with i18n](https://shipyard.levinkeller.de/docs/_llms-txt/examples/versioning-with-i18n.txt): Combine documentation versioning with internationalization
- [Why shipyard?](https://shipyard.levinkeller.de/docs/_llms-txt/why-shipyard.txt)