Referensi API

Referensi lengkap untuk semua ekspor dari paket onedocs.

Titik Masuk

Tata Letak

DocsLayout

Pembungkus tata letak utama untuk halaman dokumentasi. Menyediakan navigasi sidebar, pencarian, dan pengalih tema.

import { DocsLayout } from "onedocs";

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

Props:

• config - Objek OnedocsConfig Anda
• pageTree - Pohon halaman dari sumber Anda (misalnya e.g, source.pageTree)
• children - Konten halaman

DocsPage

Pembungkus untuk halaman dokumentasi individual. Membungkus Fumadocs UI DocsPage dan menempatkan konten di DocsBody.

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

Props:

• toc - Daftar isi dari data halaman
• children - Konten MDX
• Prop lain apa pun dari Fumadocs UI DocsPage, seperti full

DocsBody

Pembungkus bagian dalam untuk konten dokumentasi. Digunakan secara internal oleh DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Komponen halaman arahan lengkap dengan hero, fitur, dan footer.

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

Props:

• config - Objek OnedocsConfig Anda
• packageName - Nama paket untuk blok instalasi (opsional)
• children - Konten di antara fitur dan footer (opsional)

Lihat beranda dan footer untuk mengetahui hal yang diatur oleh konfigurasi.

HomeLayout

Tata letak dasar untuk beranda (digunakan secara internal oleh HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Menyusun opsi tata letak Fumadocs UI (judul navbar atau logo, nav.links dan tautan GitHub) dari konfigurasi Anda. DocsLayout dan HomeLayout menggunakannya; panggil sendiri saat Anda merender tata letak Fumadocs UI secara langsung.

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

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

Komponen

InstallBlock

Tab pengelola paket yang menampilkan perintah instalasi untuk npm, yarn, pnpm, dan bun (npm i, yarn add, pnpm add, bun add). Ini adalah komponen server asinkron.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Props:

• packageName - Nama paket npm yang akan diinstal
• title - Judul di atas tab (opsional)
• description - Teks di atas tab (opsional)
• children - Konten di bawah tab (opsional)

Button

Tautan membulat dengan gaya tombol utama. Hanya ada satu gaya.

import { Button } from "onedocs";

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

Props:

• href - Tujuan tautan
• children - Teks tombol
• className - Kelas tambahan (opsional)

Logo

Merender gambar terang dan gelap, lalu menampilkan gambar yang sesuai dengan tema saat ini. DocsLayout dan HomePage menggunakannya untuk logo dengan varian terang dan gelap.

import { Logo } from "onedocs";

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

Props:

• light - Jalur gambar untuk mode terang
• dark - Jalur gambar untuk mode gelap
• alt - Teks alt (default: "Logo")
• className - Kelas untuk kedua gambar (opsional)

CTASection

Bagian ajakan bertindak untuk beranda.

import { CTASection } from "onedocs";

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

Props:

• title - Judul bagian
• description - Teks di bawah judul (opsional)
• cta - Konfigurasi tombol dengan label dan href
• children - Konten di bawah tombol (opsional)

FontHead

Memuat font Inter Variable terlebih dahulu, mendeklarasikan @font-face-nya, lalu menetapkannya sebagai font halaman. Tambahkan ke <head> tata letak root Anda.

import { FontHead } from "onedocs";

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

Onedocs tidak menyertakan font tersebut. Secara default, FontHead memuat /fonts/InterVariable.woff2, jadi letakkan file di public/fonts/, atau berikan URL lain dengan fontPath:

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

GitHubIcon

Komponen ikon GitHub (digunakan secara internal dalam navigasi).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Blok kode dengan sorotan sintaks, disorot di server menggunakan Shiki melalui Fumadocs. Ini adalah komponen server asinkron.

import { CodeBlock } from "onedocs";

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

Konfigurasi

defineConfig

Helper konfigurasi yang aman untuk tipe.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Tipe TypeScript untuk konfigurasi.

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

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

Lihat Konfigurasi untuk semua opsi.

Utilitas Sumber

loader

Ekspor ulang loader fumadocs-core/source untuk membuat sumber konten.

import { loader } from "onedocs/source";

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

createSource

Helper untuk membuat sumber konten (pembungkus di sekitar loader). Dasar URL secara default adalah /docs.

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

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

Di 0.1.27, createSource mengembalikan sumber tanpa tipe, sehingga TypeScript melaporkan kesalahan seperti Property 'data' does not exist on type 'unknown' saat Anda membaca page.data (#4). Gunakan loader seperti yang ditunjukkan di atas sampai masalah itu diperbaiki.

Metadata

createMetadata

Membuat metadata Next.js untuk tata letak root Anda.

import { createMetadata } from "onedocs/metadata";

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

Opsi:

• baseUrl - URL dasar situs Anda (opsional)
• additional - Kolom Metadata tambahan, digabungkan terakhir (opsional)

Mengembalikan: Objek Next.js Metadata dengan:

• Judul (config.title) dan templat judul (%s | Site Name)
• Deskripsi
• Favicon dari config.icon, jika ditetapkan
• Jika baseUrl ditetapkan: metadataBase, metadata OpenGraph, dan kartu Twitter summary_large_image

createDocsPageMetadata

Membuat metadata judul dan deskripsi untuk halaman dokumentasi. Fungsi ini menerima satu objek dengan title dan description opsional.

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

Untuk gambar Open Graph per halaman, lihat Gambar OG Dinamis.

Gambar OpenGraph

createRootOGImage

Membuat gambar OG untuk beranda: logo Anda di tengah latar belakang hitam.

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

Membuat gambar OG untuk halaman dokumentasi: logo di kiri atas dan judul berwarna putih di atas latar belakang hitam. Argumen font bersifat opsional; tanpa argumen tersebut, judul menggunakan font sistem.

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

Gambar OG Dinamis

Untuk gambar OG per halaman, sajikan melalui route. Halaman tidak diarahkan ke route ini secara otomatis: tambahkan sendiri ke metadata setiap halaman, misalnya bersama openGraph: { images: "/docs/og/getting-started" } di samping kolom dari createDocsPageMetadata.

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

Fungsi Helper

File wajib:

• public/logo-dark.svg - Logo untuk gambar OG. Helper OG menentukan ukurannya dari atribut width dan height, jadi tag <svg> harus memiliki keduanya sebagai angka biasa.
• public/fonts/Inter-Medium.ttf - Font untuk judul. Onedocs tidak menyertakannya.

LLMs.txt

Buat file LLMs.txt untuk asisten AI.

generateLLMsText

Membuat konten LLMs.txt yang ringkas. Menerima sumber yang dibungkus dengan createLLMsSource dan { title, description? }, lalu mengembalikan promise.

// 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 halaman ditulis sesuai sumbernya, misalnya /docs/getting-started, tanpa domain.

generateLLMsFullText

Membuat LLMs.txt lengkap dengan konten halaman menyeluruh. Hanya menerima sumber yang sudah dibungkus, lalu mengembalikan promise.

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

Isi halaman disertakan hanya jika MDX Fumadocs includeProcessedMarkdown aktif; lihat SEO & Pencarian.

createLLMsSource

Membungkus sumber Fumadocs (hasil loader() atau createSource()) dalam bentuk yang dibaca oleh kedua fungsi di atas: URL, judul, deskripsi, dan loader teks setiap halaman.

SEO

generateSitemap

Membuat peta situs untuk dokumentasi Anda. Menerima satu objek: baseUrl, daftar pages (biasanya dari meta.json), dan docsPath opsional (default /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 ?? [],
  });
}

Lihat SEO & Pencarian untuk mengetahui cara entri menjadi URL.

generateRobots

Membuat konten robots.txt: mengizinkan semuanya, ditambah baris Host dan Sitemap. sitemapPath secara default adalah /sitemap.xml.

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

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

Preset CSS

Impor preset CSS di globals.css Anda:

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

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

Path @source relatif terhadap src/app/globals.css.

Preset ini mencakup:

• Tailwind CSS v4 (instal tailwindcss dan @tailwindcss/postcss sendiri)
• Tema netral Fumadocs
• Gaya preset Fumadocs
• --font-sans diatur ke variabel --font-inter yang didefinisikan oleh FontHead
• Fitur OpenType Inter untuk teks isi dan judul
• Gaya tata letak setinggi penuh dan penyesuaian tata letak Onedocs

Komponen MDX

Ekspor mdxComponents menyebarkan komponen Fumadocs UI bawaan MDX dan menambahkan komponen di bawah ini:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Komponen yang disertakan:

• Default Fumadocs UI: pre (blok kode), a, img, h1 hingga h6 (judul dengan anchor), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Kotak info/peringatan/kesalahan
• Card, Cards - Tata letak kartu
• Tab, Tabs - Konten bertab
• Step, Steps - Langkah bernomor
• Accordion, Accordions - Bagian yang dapat dilipat
• File, Folder, Files - Pohon file
• ImageZoom - Gambar yang dapat diperbesar
• TypeTable - Tabel dokumentasi tipe

InstallBlock dan CodeBlock tidak disertakan; tambahkan sendiri seperti yang ditunjukkan di Komponen.

Lihat Komponen untuk contoh penggunaan.