API Başvuru Kaynağı

onedocs paketindeki tüm dışa aktarımlar için eksiksiz başvuru kaynağı.

Giriş Noktaları

Düzenler

DocsLayout

Dokümantasyon sayfaları için ana düzen sarmalayıcısı. Kenar çubuğu gezintisi, arama ve tema değiştirme olanağı sunar.

import { DocsLayout } from "onedocs";

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

Özellikler:

• config - OnedocsConfig nesneniz
• pageTree - Kaynağınızdaki sayfa ağacı (e.g., source.pageTree)
• children - Sayfa içeriği

DocsPage

Tek tek dokümantasyon sayfaları için sarmalayıcı. Fumadocs UI DocsPage öğesini sarar ve içeriği DocsBody içine yerleştirir.

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>
  );
}

Özellikler:

• toc - Sayfa verilerinden alınan içindekiler tablosu
• children - MDX içeriği
• Fumadocs UI DocsPage öğesinin diğer tüm özellikleri; örneğin full

DocsBody

Dokümantasyon içeriği için iç gövde sarmalayıcısı. Dahili olarak DocsPage tarafından kullanılır.

import { DocsBody } from "onedocs";

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

HomePage

Giriş, özellikler ve altbilgi içeren tam açılış sayfası bileşeni.

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>
  );
}

Özellikler:

• config - OnedocsConfig nesneniz
• packageName - Kurulum bloğunun paket adı (isteğe bağlı)
• children - Özellikler ile altbilgi arasındaki içerik (isteğe bağlı)

Yapılandırmanın denetlediği öğeler için ana sayfaya ve altbilgiye bakın.

HomeLayout

Ana sayfanın temel düzeni (dahili olarak HomePage tarafından kullanılır).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Yapılandırmanızdan Fumadocs UI düzen seçeneklerini (navbar başlığı veya logosu, nav.links ve GitHub bağlantısı) oluşturur. DocsLayout ve HomeLayout bunu kullanır; bir Fumadocs UI düzenini doğrudan oluştururken kendiniz çağırın.

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

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

Bileşenler

InstallBlock

npm, yarn, pnpm ve bun için kurulum komutlarını gösteren paket yöneticisi sekmeleri (npm i, yarn add, pnpm add, bun add). Bu, eşzamansız bir sunucu bileşenidir.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Özellikler:

• packageName - Yüklenecek npm paket adı
• title - Sekmelerin üstündeki başlık (isteğe bağlı)
• description - Sekmelerin üstündeki metin (isteğe bağlı)
• children - Sekmelerin altındaki içerik (isteğe bağlı)

Button

Birincil düğme biçiminde stillendirilmiş yuvarlak bağlantı. Tek bir stili vardır.

import { Button } from "onedocs";

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

Özellikler:

• href - Bağlantı hedefi
• children - Düğme metni
• className - Ek sınıflar (isteğe bağlı)

Logo

Açık ve koyu birer görsel oluşturur, ardından geçerli temaya uyanı gösterir. DocsLayout ve HomePage, açık ve koyu varyantları olan bir logo için bunu kullanır.

import { Logo } from "onedocs";

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

Özellikler:

• light - Açık mod için görsel yolu
• dark - Koyu mod için görsel yolu
• alt - Alternatif metin (varsayılan: "Logo")
• className - Her iki görsel için sınıflar (isteğe bağlı)

CTASection

Ana sayfa için eylem çağrısı bölümü.

import { CTASection } from "onedocs";

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

Özellikler:

• title - Bölüm başlığı
• description - Başlığın altındaki metin (isteğe bağlı)
• cta - label ve href içeren düğme yapılandırması
• children - Düğmenin altındaki içerik (isteğe bağlı)

FontHead

Inter Variable yazı tipini önceden yükler, @font-face tanımlar ve bunu sayfanın yazı tipi olarak ayarlar. Kök düzeninizin <head> bölümüne ekleyin.

import { FontHead } from "onedocs";

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

Onedocs yazı tipi dosyasını içermez. Varsayılan olarak FontHead, /fonts/InterVariable.woff2 dosyasını yükler; bu nedenle dosyayı public/fonts/ içine koyun veya fontPath ile başka bir URL geçirin:

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

GitHubIcon

GitHub simge bileşeni (gezintide dahili olarak kullanılır).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Sözdizimi vurgulanmış kod bloğu; sunucuda Shiki ile Fumadocs aracılığıyla vurgulanır. Bu, eşzamansız bir sunucu bileşenidir.

import { CodeBlock } from "onedocs";

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

Yapılandırma

defineConfig

Tür güvenli yapılandırma yardımcısı.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Yapılandırma için TypeScript türü.

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

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

Tüm seçenekler için Yapılandırma sayfasına bakın.

Kaynak Yardımcıları

loader

İçerik kaynakları oluşturmak için fumadocs-core/source yükleyicisinin yeniden dışa aktarımı.

import { loader } from "onedocs/source";

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

createSource

İçerik kaynağı oluşturmak için yardımcı (yükleyici etrafında sarmalayıcı). Temel URL varsayılanı /docs değeridir.

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

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

0.1.27 createSource içinde tür belirtilmemiş bir kaynak döndürür; bu nedenle TypeScript, page.data öğesini okurken Property 'data' does not exist on type 'unknown' gibi hatalar bildirir (#4). Bu düzeltilene kadar yukarıda gösterildiği gibi loader kullanın.

Meta Veriler

createMetadata

Kök düzeniniz için Next.js meta verilerini oluşturur.

import { createMetadata } from "onedocs/metadata";

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

Seçenekler:

• baseUrl - Sitenizin temel URL'i (isteğe bağlı)
• additional - En son birleştirilen ek Metadata alanları (isteğe bağlı)

Döndürdüğü değer: Şunları içeren Next.js Metadata nesnesi:

• Başlık (config.title) ve başlık şablonu (%s | Site Name)
• Açıklama
• Ayarlanmışsa config.icon simgesi
• baseUrl ayarlandığında: metadataBase, OpenGraph meta verileri ve Twitter summary_large_image kartı

createDocsPageMetadata

Bir dokümantasyon sayfasının başlık ve açıklama meta verilerini oluşturur. title ve isteğe bağlı bir description içeren tek bir nesne alır.

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,
  });
}

Sayfaya özel bir Open Graph görseli için bkz. Dinamik OG Görselleri.

OpenGraph Görselleri

createRootOGImage

Ana sayfa için bir OG görseli oluşturur: siyah arka plan üzerinde ortalanmış logonuz.

// 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

Dokümantasyon sayfaları için bir OG görseli oluşturur: logo sol üstte, başlık siyah zemin üzerinde beyazdır. Font bağımsız değişkeni isteğe bağlıdır; belirtilmezse başlıkta sistem fontu kullanılır.

// 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);
}

Dinamik OG Görselleri

Sayfaya özel OG görselleri için bunları bir route üzerinden sunun. Sayfalar bu route'a otomatik olarak yönlendirilmez: örneğin, createDocsPageMetadata'den gelen alanların yanına openGraph: { images: "/docs/og/getting-started" } ekleyerek her sayfanın meta verilerine kendiniz ekleyin.

// 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);
}

Yardımcı İşlevler

Gerekli dosyalar:

• public/logo-dark.svg - OG görselleri için logo. OG yardımcıları boyutunu width ve height özniteliklerinden alır; bu nedenle <svg> etiketi her ikisini de düz sayı olarak içermelidir.
• public/fonts/Inter-Medium.ttf - Başlıklar için font. Onedocs bunu içermez.

LLMs.txt

Yapay zekâ asistanları için LLMs.txt dosyaları oluşturun.

generateLLMsText

Özet LLMs.txt içeriği oluşturur. createLLMsSource ve { title, description? } ile sarmalanmış bir kaynak alır ve bir promise döndürür.

// 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" },
  });
}

Sayfa URL'leri, alan adı olmadan, örneğin /docs/getting-started, kaynakta geldikleri biçimde yazılır.

generateLLMsFullText

Eksiksiz sayfa içeriğiyle tam LLMs.txt oluşturur. Yalnızca sarmalanmış kaynağı alır ve bir promise döndürür.

// 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" },
  });
}

Sayfa gövdeleri yalnızca Fumadocs MDX'ın includeProcessedMarkdown seçeneği açıksa eklenir; bkz. SEO ve Arama.

createLLMsSource

Bir Fumadocs kaynağını (loader() veya createSource() sonucu) yukarıdaki iki işlevin okuduğu yapıda sarar: her sayfanın URL, başlığı, açıklaması ve metin yükleyicileri.

SEO

generateSitemap

Dokümantasyonunuz için bir site haritası oluşturur. Tek bir nesne alır: baseUrl, pages listesi (genellikle meta.json kaynağından gelir) ve isteğe bağlı bir docsPath (varsayılanı /docs).

// 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 ?? [],
  });
}

Girdilerin URL'lere nasıl dönüştüğünü görmek için SEO ve Arama bölümüne bakın.

generateRobots

robots.txt içeriği oluşturur: her şeye izin verir, ayrıca Host ve Sitemap satırlarını ekler. sitemapPath varsayılan olarak /sitemap.xml değerini alır.

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

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

CSS Ön Ayarı

CSS ön ayarını globals.css dosyanıza aktarın:

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

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

@source yolları, src/app/globals.css konumuna göreli olarak tanımlanır.

Ön ayar şunları içerir:

• Tailwind CSS v4 (tailwindcss ve @tailwindcss/postcss öğelerini kendiniz yükleyin)
• Fumadocs nötr tema
• Fumadocs ön ayar stilleri
• FontHead tarafından tanımlanan --font-inter değişkenine ayarlanmış --font-sans
• Gövde metni ve başlıklar için Inter OpenType özellikleri
• Tam yükseklikli düzen stilleri ve Onedocs düzen ayarları

MDX Bileşenleri

mdxComponents dışa aktarımı, Fumadocs UI varsayılan MDX bileşenlerini yayar ve aşağıdaki bileşenleri ekler:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Dahil edilen bileşenler:

• Fumadocs UI varsayılanları: pre (kod blokları), a, img, h1 ile h6 (bağlantı sabitleyicili başlıklar), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Bilgi/uyarı/hata bildirim kutuları
• Card, Cards - Kart düzenleri
• Tab, Tabs - Sekmeli içerik
• Step, Steps - Numaralı adımlar
• Accordion, Accordions - Daraltılabilir bölümler
• File, Folder, Files - Dosya ağaçları
• ImageZoom - Yakınlaştırılabilir görseller
• TypeTable - Tür dokümantasyonu tabloları

InstallBlock ve CodeBlock dahil değildir; bunları Bileşenler bölümünde gösterildiği gibi kendiniz ekleyin.

Kullanım örnekleri için Bileşenler bölümüne bakın.