# Documentation

Guidelines for contributing to the Skeleton documentation website.

## Astro

The Skeleton documentation website is maintained using the Astro framework.

### Integrations

Review the full list of integrations in `astro.config.js`.

* [AutoImport](https://github.com/delucis/astro-auto-import)
* [Svelte](https://docs.astro.build/en/guides/integrations-guide/svelte/)
* [React](https://docs.astro.build/en/guides/integrations-guide/react/)
* [MDX](https://docs.astro.build/en/guides/markdown-content/)
* [Partytown](https://docs.astro.build/en/guides/integrations-guide/partytown/)
* [Sitemap](https://docs.astro.build/en/guides/integrations-guide/sitemap/)
* [PageFind](https://github.com/shishkin/astro-pagefind)

## Project Structure

Navigate the project structure within the `src` directory. This includes the following directories:

\| Path             | Description                                                                                                |
\| ---------------- | ---------------------------------------------------------------------------------------------------------- |
\| `src/components` | Contains the documentation components.                                                                     |
\| `src/content`    | Contains the documentation [Content Collections](https://docs.astro.build/en/guides/content-collections/). |
\| `src/modules`    | Contains the documentation modules.                                                                        |
\| `src/pages`      | Contains the documentation pages and endpoints.                                                            |
\| `src/assets`     | Contains the documentation images, vector graphics and other assets.                                       |

### src/components

#### Example Components

The `src/components/examples` directory contains all example components used within the documentation pages.

#### Astro Layout Components

The `src/components/layouts` directory contains all layout components used throughout the docs.

* `root-layout.astro`: The root layout for the documentation website containing the globally used `<head>`.
* `docs-layout.astro`: The layout for all documentation pages within the `/docs` section.

#### MDX Typography Components

The `src/components/typography` directory contains all [MDX typography components](https://mdxjs.com/table-of-components/) used throughout the docs, such as headings, lists, and anchors.

#### Documentation Components

The `src/components/ui` directory contains all global UI components used throughout the docs.

##### The Framework Component

The `<Framework>` component you to display framework-aware content. Tailored specifically for that framework.

```mdx
<Framework id="react">This is React specific content.</Framework>
<Framework id="svelte">This is Svelte specific content.</Framework>
```

> This component shows content based on the url parameter, e.g. `/docs/react` or `/docs/svelte`.

##### The Preview Component

Allows you to quickly toggle between an example component and its source code.

```mdx
import Default from '@/components/examples/foo/default';
import DefaultRaw from '@/components/examples/foo/default?raw';

<Preview files={{ 'app.astro': DefaultRaw }} client:visible>
	<Default />
</Preview>
```

> This component is auto-imported in all mdx files, so you do not need to manually import it.

##### The API Reference Component

Allows you to display an API reference table for a specific component.

```mdx
<ApiReference id="svelte/accordion" />
```

> This component is auto-imported in all mdx files, so you do not need to manually import it.

### src/content

#### Documentation

The `src/content/docs` directory contains all the documentation pages, any `.md`/`.mdx` files placed here will automatically be routed within the `/docs` section of the website.

#### Frameworks

The `src/content/frameworks` directory contains a JSON collection of all supported frameworks for Skeleton, used to power framework switchers and other framework specific content.

#### Showcase

The `src/content/showcase-projects` directory contains a JSON collection of all showcased projects on the [Showcase](/showcase) page.

### src/modules

The `src/modules` directory contains all modules for the documentation website, including utility functions and shared logic.

### src/pages

The `src/pages` directory contains all pages and routes for the documentation website, you generally will not need to edit files in this directory.

### src/assets

The `src/assets` directory contains all assets for the documentation website, including images and SVGs.

## Global Components

A suite of global components are automatically imported within MDX pages via [astro-auto-importer](https://github.com/delucis/astro-auto-import/tree/main/packages/astro-auto-import). These components are configure via `astro.config.mjs` > `AutoImport()` in the project root.

* `<Framework>` - Allows for implementing content specific for one framework.
* `<ApiReference>` - Displays the table of API reference data per component.
* `<Preview>` - Shows a live preview of a Skeleton feature.
* `<Alert>` - Display a very simple alert message.

## Iconography

This documentation application utilizes [Lucide](https://lucide.dev/guide/packages/lucide-svelte) for its icons.

```tsx
import { SkullIcon } from 'lucide-react';

export default function App() {
	return <SkullIcon stroke="pink" className="size-8" />;
}
```
