# Referință API

Referință completă pentru toate exporturile pachetului `onedocs`.

## Puncte de intrare

| Import | Descriere |
|--------|-------------|
| `onedocs` | Intrare principală - machete, componente, `mdxComponents`, `defineConfig`, funcții auxiliare pentru surse |
| `onedocs/components` | Componente Fumadocs UI plus `InstallBlock`, `CodeBlock`, `Button` și `Logo` |
| `onedocs/config` | Funcții auxiliare de configurare |
| `onedocs/source` | Utilitare pentru surse de conținut |
| `onedocs/metadata` | Generarea metadatelor |
| `onedocs/og` | Generarea imaginilor OpenGraph |
| `onedocs/llms` | Generarea LLMs.txt |
| `onedocs/seo` | Sitemap și robots.txt |
| `onedocs/css/preset.css` | Configurație presetată Tailwind CSS |

## Aspecte

### DocsLayout

Componentă principală pentru paginile documentației. Oferă navigare laterală, căutare și comutarea temei.

```tsx
import { DocsLayout } from "onedocs";

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <DocsLayout config={config} pageTree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}
```

**Proprietăți:**
- `config` - Obiectul dvs. `OnedocsConfig`
- `pageTree` - Arborele paginilor din sursa dvs. (de ex., e.g, `source.pageTree`)
- `children` - Conținutul paginii

### DocsPage

Componentă de încadrare pentru pagini individuale ale documentației. Încadrează Fumadocs UI `DocsPage` și plasează conținutul în `DocsBody`.

```tsx
import { DocsPage, mdxComponents } from "onedocs";
import { notFound } from "next/navigation";

export default async function Page(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();
  const MDX = page.data.body;

  return (
    <DocsPage toc={page.data.toc}>
      <MDX components={mdxComponents} />
    </DocsPage>
  );
}
```

**Proprietăți:**
- `toc` - Cuprinsul din datele paginii
- `children` - Conținutul MDX
- Orice altă proprietate a Fumadocs UI `DocsPage`, precum `full`

### DocsBody

Componentă interioară de încadrare pentru conținutul documentației. Folosită intern de `DocsPage`.

```tsx
import { DocsBody } from "onedocs";

<DocsBody>
  <MDX components={mdxComponents} />
</DocsBody>
```

### HomePage

Componentă completă pentru pagina de destinație, cu secțiune principală, funcționalități și subsol.

```tsx
import { HomePage, CTASection } from "onedocs";

export default function Home() {
  return (
    <HomePage config={config} packageName="my-package">
      <CTASection
        title="Ready to get started?"
        cta={{ label: "Read the Docs", href: "/docs" }}
      />
    </HomePage>
  );
}
```

**Proprietăți:**
- `config` - Obiectul dvs. `OnedocsConfig`
- `packageName` - Numele pachetului pentru blocul de instalare (opțional)
- `children` - Conținutul dintre funcționalități și subsol (opțional)

Consultați pagina principală [homepage](https://onedocs.inline0.dev/ro/docs/configuration#homepage) și subsolul [footer](https://onedocs.inline0.dev/ro/docs/configuration#footer) pentru a vedea ce controlează configurația.

### HomeLayout

Aspect de bază pentru pagina principală (folosit intern de `HomePage`).

```tsx
import { HomeLayout } from "onedocs";

<HomeLayout config={config}>
  {/* Custom homepage content */}
</HomeLayout>
```

### createBaseOptions

Construiește opțiunile de aspect Fumadocs UI (titlul sau sigla barei de navigare, `nav.links` și linkul GitHub) din configurația dvs. `DocsLayout` și `HomeLayout` îl folosesc; apelați-l direct când redați un aspect Fumadocs UI.

```tsx
import { DocsLayout } from "fumadocs-ui/layouts/docs";
import { createBaseOptions } from "onedocs";

<DocsLayout {...createBaseOptions(config)} tree={source.pageTree}>
  {children}
</DocsLayout>
```

## Componente

### InstallBlock

Filele managerelor de pachete afișează comenzile de instalare pentru npm, yarn, pnpm și bun (`npm i`, `yarn add`, `pnpm add`, `bun add`). Este o componentă de server asincronă.

```tsx
import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />
```

**Proprietăți:**
- `packageName` - Numele pachetului npm de instalat
- `title` - Titlul de deasupra filelor (opțional)
- `description` - Textul de deasupra filelor (opțional)
- `children` - Conținutul de sub file (opțional)

### Button

Link rotunjit, stilizat ca buton principal. Există un singur stil.

```tsx
import { Button } from "onedocs";

<Button href="/docs">Get Started</Button>
```

**Proprietăți:**
- `href` - Destinația linkului
- `children` - Textul butonului
- `className` - Clase suplimentare (opțional)

### Logo

Randează o imagine pentru tema luminoasă și una pentru tema întunecată și o afișează pe cea potrivită temei curente. `DocsLayout` și `HomePage` o folosesc pentru un `logo` cu variante pentru tema luminoasă și cea întunecată.

```tsx
import { Logo } from "onedocs";

<Logo light="/logo-light.svg" dark="/logo-dark.svg" alt="My Project" className="h-6" />
```

**Proprietăți:**
- `light` - Calea imaginii pentru tema luminoasă
- `dark` - Calea imaginii pentru tema întunecată
- `alt` - Text alternativ (implicit: `"Logo"`)
- `className` - Clase pentru ambele imagini (opțional)

### CTASection

Secțiune cu îndemn la acțiune pentru pagina principală.

```tsx
import { CTASection } from "onedocs";

<CTASection
  title="Ready to get started?"
  description="Optional description text"
  cta={{ label: "Get Started", href: "/docs" }}
/>
```

**Proprietăți:**
- `title` - Titlul secțiunii
- `description` - Textul de sub titlu (opțional)
- `cta` - Configurația butonului cu `label` și `href`
- `children` - Conținutul de sub buton (opțional)

### FontHead

Preîncarcă fontul Inter Variable, îi declară `@font-face` și îl setează ca font al paginii. Adăugați-l la `<head>` din layoutul rădăcină.

```tsx
import { FontHead } from "onedocs";

<html>
  <head>
    <FontHead />
  </head>
  <body>{children}</body>
</html>
```

Onedocs nu include fontul. În mod implicit, `FontHead` încarcă `/fonts/InterVariable.woff2`, așadar plasați fișierul în `public/fonts/` sau transmiteți un alt URL cu `fontPath`:

```tsx
<FontHead fontPath="/assets/Inter.woff2" />
```

### GitHubIcon

Componenta de pictogramă GitHub (folosită intern în navigare).

```tsx
import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />
```

### CodeBlock

Bloc de cod cu evidențierea sintaxei, evidențiat pe server cu Shiki până la Fumadocs. Este o componentă de server asincronă.

```tsx
import { CodeBlock } from "onedocs";

<CodeBlock lang="tsx" code="const x = 1;" />
```

## Configurare

### defineConfig

Funcție ajutătoare pentru configurații sigure din punct de vedere al tipurilor.

```tsx
import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Docs",
  // ... other options
});
```

### OnedocsConfig

Tipul TypeScript pentru configurație.

```tsx
import type { OnedocsConfig } from "onedocs/config";

const config: OnedocsConfig = {
  title: "My Docs",
};
```

Consultați [Configurare](https://onedocs.inline0.dev/ro/docs/configuration) pentru toate opțiunile.

## Utilitare pentru surse

### loader

Reexportă funcția loader `fumadocs-core/source` pentru crearea surselor de conținut.

```tsx
import { loader } from "onedocs/source";

export const source = loader({
  baseUrl: "/docs",
  source: docs.toFumadocsSource(),
});
```

### createSource

Funcție ajutătoare pentru crearea unei surse de conținut (un wrapper peste loader). Baza URL este implicit `/docs`.

```tsx
import { createSource } from "onedocs/source";
import { docs } from "../../.source/server";

export const source = createSource(docs);
// export const source = createSource(docs, { baseUrl: "/guide" });
```

În 0.1.27, `createSource` returnează o sursă fără tip, astfel că TypeScript raportează erori precum `Property 'data' does not exist on type 'unknown'` când citiți `page.data` ([Problema #4](https://github.com/inline0/onedocs/issues/4)). Folosiți `loader`, așa cum se arată mai sus, până când problema este remediată.

## Metadate

### createMetadata

Generează metadatele Next.js pentru layoutul rădăcină.

```tsx
import { createMetadata } from "onedocs/metadata";

export const metadata = createMetadata(config, {
  baseUrl: "https://example.com",
});
```

**Opțiuni:**
- `baseUrl` - URL de bază al site-ului (opțional)
- `additional` - Câmpuri `Metadata` suplimentare, unite la final (opțional)

**Returnează:** obiectul Next.js `Metadata` cu:
- Titlul (`config.title`) și șablonul titlului (`%s | Site Name`)
- Descrierea
- Pictograma favicon din `config.icon`, dacă este setată
- Când `baseUrl` este setat: `metadataBase`, metadate OpenGraph și un card Twitter `summary_large_image`

### createDocsPageMetadata

Generează metadatele pentru titlu și descriere ale unei pagini de documentație. Primește un obiect cu `title` și un `description` opțional.

```tsx
import { createDocsPageMetadata } from "onedocs/metadata";
import { notFound } from "next/navigation";

export async function generateMetadata(props: {
  params: Promise<{ slug?: string[] }>;
}) {
  const params = await props.params;
  const page = source.getPage(params.slug);
  if (!page) notFound();

  return createDocsPageMetadata({
    title: page.data.title,
    description: page.data.description,
  });
}
```

Pentru o imagine Open Graph specifică unei pagini, consultați [Imagini OG dinamice](#dynamic-og-images).

## Imagini OpenGraph

### createRootOGImage

Creează o imagine OG pentru pagina principală: logo-ul centrat pe un fundal negru.

```tsx
// src/app/opengraph-image.tsx
import {
  createRootOGImage,
  loadPublicFile,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const logo = await loadPublicFile("logo-dark.svg");
  return createRootOGImage(logo as OGImageLogo);
}
```

### createDocsOGImage

Creează o imagine OG pentru paginile de documentație: logo-ul în stânga sus și titlul alb pe fundal negru. Argumentul fontului este opțional; fără acesta, titlul folosește fontul sistemului.

```tsx
// src/app/docs/opengraph-image.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  ogImageSize,
  ogImageContentType,
  type OGImageLogo,
} from "onedocs/og";

export const size = ogImageSize;
export const contentType = ogImageContentType;

export default async function Image() {
  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);
  return createDocsOGImage("Documentation", logo as OGImageLogo, font);
}
```

### Imagini OG dinamice

Pentru imaginile OG specifice fiecărei pagini, serviți-le dintr-o rută. Paginile nu sunt direcționate automat către această rută: adăugați-o manual la metadatele fiecărei pagini, de exemplu cu `openGraph: { images: "/docs/og/getting-started" }` alături de câmpurile din `createDocsPageMetadata`.

```tsx
// src/app/docs/og/[...slug]/route.tsx
import {
  createDocsOGImage,
  loadPublicFile,
  loadInterFont,
  type OGImageLogo,
} from "onedocs/og";
import { source } from "@/lib/source";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ slug: string[] }> }
) {
  const { slug } = await params;
  const page = source.getPage(slug);
  const title = page?.data.title ?? "Documentation";

  const [logo, font] = await Promise.all([
    loadPublicFile("logo-dark.svg"),
    loadInterFont(),
  ]);

  return createDocsOGImage(title, logo as OGImageLogo, font);
}
```

### Funcții ajutătoare

| Funcție | Descriere |
|----------|-------------|
| `loadPublicFile(path)` | Încarcă un fișier din `public/` ca date URL și buffer; pentru SVG-uri citește și atributele `width` și `height` |
| `loadInterFont(path?)` | Încarcă un font din `public/` pentru imaginile OG, implicit `fonts/Inter-Medium.ttf` |
| `ogImageSize` | Dimensiunile standard ale imaginii OG `{ width: 1200, height: 630 }` |
| `ogImageContentType` | MIME tip `"image/png"` |

**Fișiere necesare:**
- `public/logo-dark.svg` - Logo pentru imaginile OG. Funcțiile ajutătoare OG îi stabilesc dimensiunea pe baza atributelor `width` și `height`, așadar eticheta `<svg>` trebuie să le aibă pe ambele ca numere simple.
- `public/fonts/Inter-Medium.ttf` - Font pentru titluri. Onedocs nu îl include.

## LLMs.txt

Generează fișiere LLMs.txt pentru asistenții AI.

### generateLLMsText

Generează conținut LLMs.txt concis. Primește o sursă împachetată cu `createLLMsSource` și `{ title, description? }` și returnează o promisiune.

```tsx
// src/app/llms.txt/route.ts
import { createLLMsSource, generateLLMsText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsText(createLLMsSource(source), {
    title: "My Project",
    description: "Project description",
  });

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

URL-urile paginilor sunt scrise exact cum provin din sursă, de exemplu `/docs/getting-started`, fără domeniu.

### generateLLMsFullText

Generează LLMs.txt complet, cu tot conținutul paginii. Primește doar sursa împachetată și returnează o promisiune.

```tsx
// src/app/llms-full.txt/route.ts
import { createLLMsSource, generateLLMsFullText } from "onedocs/llms";
import { source } from "@/lib/source";

export async function GET() {
  const content = await generateLLMsFullText(createLLMsSource(source));

  return new Response(content, {
    headers: { "Content-Type": "text/plain; charset=utf-8" },
  });
}
```

Corpurile paginilor sunt incluse doar când Fumadocs MDX al lui are `includeProcessedMarkdown` activat; consultați [SEO și căutare](https://onedocs.inline0.dev/ro/docs/seo-search#full-content-version).

### createLLMsSource

Împachetează o sursă Fumadocs (rezultat `loader()` sau `createSource()`) în forma așteptată de cele două funcții de mai sus: URL, titlul, descrierea și încărcătoarele de text ale fiecărei pagini.

## SEO

### generateSitemap

Generează o hartă a site-ului pentru documentație. Primește un singur obiect: `baseUrl`, lista `pages` (de obicei din `meta.json`) și un `docsPath` opțional (implicit `/docs`).

```tsx
// src/app/sitemap.ts
import { generateSitemap } from "onedocs/seo";
import meta from "../../content/docs/meta.json";

export default function sitemap() {
  return generateSitemap({
    baseUrl: "https://example.com",
    pages: meta.pages ?? [],
  });
}
```

Consultați [SEO și căutare](https://onedocs.inline0.dev/ro/docs/seo-search#sitemap) pentru a afla cum devin intrările URL-uri.

### generateRobots

Generează conținut robots.txt: permite totul, plus liniile `Host` și `Sitemap`. `sitemapPath` are implicit valoarea `/sitemap.xml`.

```tsx
// src/app/robots.ts
import { generateRobots } from "onedocs/seo";

export default function robots() {
  return generateRobots({
    baseUrl: "https://example.com",
  });
}
```

## Presetare CSS

Importați presetarea CSS în `globals.css`:

```css
@import "onedocs/css/preset.css";

@source "./**/*.tsx";
@source "../../content/**/*.mdx";
```

Căile `@source` sunt relative la `src/app/globals.css`.

Presetarea include:
- Tailwind CSS v4 (instalați voi `tailwindcss` și `@tailwindcss/postcss`)
- Temă neutră Fumadocs
- Stiluri de presetare Fumadocs
- `--font-sans` setat la variabila `--font-inter` definită de `FontHead`
- Funcții OpenType Inter pentru textul corpului și titluri
- Stiluri de layout pe toată înălțimea și ajustările de layout Onedocs

## Componente MDX

Exportul `mdxComponents` extinde componentele implicite Fumadocs UI MDX și adaugă componentele de mai jos:

```tsx
import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />
```

**Componente incluse:**
- Componente implicite din Fumadocs UI: `pre` (blocuri de cod), `a`, `img`, `h1` la `h6` (titluri cu ancore), `table`, `CodeBlockTab`, `CodeBlockTabs`, `CodeBlockTabsList`, `CodeBlockTabsTrigger`, `CalloutContainer`, `CalloutTitle`, `CalloutDescription`
- `Callout` - Casete informative, de avertizare și de eroare
- `Card`, `Cards` - Aspecte cu carduri
- `Tab`, `Tabs` - Conținut cu file
- `Step`, `Steps` - Pași numerotați
- `Accordion`, `Accordions` - Secțiuni restrângibile
- `File`, `Folder`, `Files` - Arbori de fișiere
- `ImageZoom` - Imagini cu zoom
- `TypeTable` - Tabele de documentare a tipurilor

`InstallBlock` și `CodeBlock` nu sunt incluse; adăugați-le conform exemplului din [Componente](https://onedocs.inline0.dev/ro/docs/components#more-components).

Consultați [Componente](https://onedocs.inline0.dev/ro/docs/components) pentru exemple de utilizare.