API-viiteopas

Kattava opas kaikista onedocs-paketin viennistä.

Aloituskohdat

Asetteluja

DocsLayout

Dokumentaatiosivujen asettelun pääkääre. Tarjoaa sivupalkin navigoinnin, haun ja teeman vaihdon.

import { DocsLayout } from "onedocs";

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

Ominaisuudet:

• config – OnedocsConfig-objektisi
• pageTree – sivupuu lähteestäsi (e.g, source.pageTree)
• children – sivun sisältö

DocsPage

Yksittäisten dokumentaatiosivujen kääre. Käärii Fumadocs UI DocsPage ja sijoittaa sisällön kohteeseen 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>
  );
}

Ominaisuudet:

• toc – sivun tiedoista saatu sisällysluettelo
• children – MDX-sisältö
• Kaikki muut Fumadocs UI DocsPage-komponentin ominaisuudet, kuten full

DocsBody

Dokumentaatiosisällön sisempi kääre. Käytössä sisäisesti kohteessa DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Koko etusivun komponentti, jossa on hero-osio, ominaisuudet ja alatunniste.

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

Ominaisuudet:

• config – OnedocsConfig-objektisi
• packageName – asennuslohkon paketin nimi (valinnainen)
• children – ominaisuuksien ja alatunnisteen välinen sisältö (valinnainen)

Katso, mitä asetukset määrittävät: etusivu ja alatunniste.

HomeLayout

Etusivun perusasettelu (käytössä sisäisesti kohteessa HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Luo asetuksistasi Fumadocs UI-asetteluvaihtoehdot (navigointipalkin otsikko tai logo, nav.links ja GitHub-linkki). DocsLayout ja HomeLayout käyttävät sitä; kutsu sitä itse, kun renderöit suoraan Fumadocs UI-asettelun.

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

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

Komponentit

InstallBlock

Pakettienhallinnan välilehdet, jotka näyttävät asennuskomennot paketeille npm, yarn, pnpm ja bun (npm i, yarn add, pnpm add, bun add). Tämä on asynkroninen palvelinkomponentti.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Ominaisuudet:

• packageName – asennettavan npm-paketin nimi
• title – välilehtien yläpuolella oleva otsikko (valinnainen)
• description – välilehtien yläpuolella oleva teksti (valinnainen)
• children – välilehtien alla oleva sisältö (valinnainen)

Button

Pyöristetty linkki, joka on muotoiltu ensisijaiseksi painikkeeksi. Käytössä on yksi tyyli.

import { Button } from "onedocs";

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

Ominaisuudet:

• href – linkin kohde
• children – painikkeen teksti
• className – lisäluokat (valinnainen)

Logo

Näyttää vaalean ja tumman kuvan ja valitsee niistä nykyiseen teemaan sopivan. DocsLayout ja HomePage käyttävät sitä kohteen logo kanssa, jolle on vaalea ja tumma versio.

import { Logo } from "onedocs";

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

Ominaisuudet:

• light – kuvan polku vaaleassa tilassa
• dark – kuvan polku tummassa tilassa
• alt – vaihtoehtoinen teksti (oletus: "Logo")
• className – molempien kuvien luokat (valinnainen)

CTASection

Etusivun toimintakehotusosio.

import { CTASection } from "onedocs";

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

Ominaisuudet:

• title – osion otsikko
• description – otsikon alla oleva teksti (valinnainen)
• cta – painikkeen asetukset, joissa ovat label ja href
• children – painikkeen alla oleva sisältö (valinnainen)

FontHead

Esilataa Inter Variable -fontin, määrittää sen @font-face-arvon ja asettaa sen sivun fontiksi. Lisää se juuriasettelusi kohteeseen <head>.

import { FontHead } from "onedocs";

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

Onedocs ei sisällä fonttia. Oletusarvoisesti FontHead lataa /fonts/InterVariable.woff2, joten sijoita tiedosto kohteeseen public/fonts/ tai välitä toinen URL kohteen fontPath kanssa:

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

GitHubIcon

GitHub-kuvakekomponentti (käytössä sisäisesti navigoinnissa).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Syntaksikorostettu koodilohko, jonka korostus tehdään palvelimella käyttäen Shiki- ja Fumadocs-arvoja. Tämä on asynkroninen palvelinkomponentti.

import { CodeBlock } from "onedocs";

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

Määritykset

defineConfig

Tyyppiturvallinen asetusten apufunktio.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

TypeScript-tyyppi asetuksille.

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

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

Katso kaikki vaihtoehdot kohdasta Asetukset.

Lähdeapuohjelmat

loader

fumadocs-core/source-lataajan uudelleenvienti sisältölähteiden luomiseen.

import { loader } from "onedocs/source";

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

createSource

Apufunktio sisältölähteen luomiseen (lataajan kääre). Perus-URL-arvona on oletuksena /docs.

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

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

Kohteessa 0.1.27 createSource palauttaa tyypittämättömän lähteen, joten TypeScript ilmoittaa virheistä, kuten Property 'data' does not exist on type 'unknown', kun luet kohdetta page.data (#4). Käytä yllä kuvattua loader, kunnes ongelma on korjattu.

Metatiedot

createMetadata

Luo juuriasettelullesi Next.js-metatiedot.

import { createMetadata } from "onedocs/metadata";

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

Asetukset:

• baseUrl – sivustosi perus-URL (valinnainen)
• additional – ylimääräiset Metadata-kentät, jotka yhdistetään viimeiseksi (valinnainen)

Palauttaa: Next.js Metadata-objektin, jossa ovat:

• Otsikko (config.title) ja otsikkomalli (%s | Site Name)
• Kuvaus
• Suosikkikuvake kohteesta config.icon, jos asetettu
• Jos baseUrl on asetettu: metadataBase, OpenGraph-metatiedot ja Twitter summary_large_image-kortti

createDocsPageMetadata

Luo dokumentaatiosivun otsikon ja kuvauksen metatiedot. Saa yhden objektin, jossa on title ja valinnainen description.

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

Katso sivukohtaiset Open Graph-kuvat kohdasta Dynaamiset OG-kuvat.

OpenGraph-kuvat

createRootOGImage

Luo etusivulle OG-kuvan, jossa logo on keskellä mustaa taustaa.

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

Luo dokumentaatiosivuille OG-kuvan, jossa logo on vasemmassa yläkulmassa ja otsikko valkoisena mustalla taustalla. Fonttiargumentti on valinnainen; ilman sitä otsikossa käytetään järjestelmäfonttia.

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

Dynaamiset OG-kuvat

Tarjoa sivukohtaiset OG-kuvat reitiltä. Sivut eivät viittaa tähän reittiin automaattisesti: lisää se kunkin sivun metatietoihin itse, esimerkiksi kohteen createDocsPageMetadata kenttien viereen muodossa openGraph: { images: "/docs/og/getting-started" }.

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

Apuohjelmat

Vaaditut tiedostot:

• public/logo-dark.svg – OG-kuvien logo. OG-apuohjelmat määrittävät sen koon width- ja height-attribuuttien perusteella, joten <svg>-tunnisteessa molempien on oltava tavallisia numeroita.
• public/fonts/Inter-Medium.ttf – otsikoiden fontti. Onedocs ei sisällä sitä.

LLMs.txt

Luo LLMs.txt-tiedostoja tekoälyavustajille.

generateLLMsText

Luo ytimekästä LLMs.txt-sisältöä. Saa lähteen, joka on kääritty kohteilla createLLMsSource ja { title, description? }, ja palauttaa lupauksen.

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

Sivujen URL-osoitteet kirjoitetaan lähteen mukaisina, esimerkiksi /docs/getting-started, ilman verkkotunnusta.

generateLLMsFullText

Luo täydellisen LLMs.txt-sisällön kaikkine sivujen sisältöineen. Saa vain käärityn lähteen ja palauttaa lupauksen.

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

Sivujen rungot sisällytetään vain, kun Fumadocs MDXn includeProcessedMarkdown on käytössä; katso SEO ja haku.

createLLMsSource

Käärii Fumadocs-lähteen (loader()- tai createSource()-tuloksen) muotoon, jota yllä olevat kaksi funktiota käyttävät: kunkin sivun URL sekä otsikko, kuvaus ja tekstilataajat.

SEO

generateSitemap

Luo dokumentaatiollesi sivustokartan. Saa yhden objektin: baseUrl, pages-luettelon (yleensä kohteesta meta.json) sekä valinnaisen docsPath-arvon (oletus /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 ?? [],
  });
}

Katso kohdasta SEO ja haku, miten merkinnät muuttuvat URL-osoitteiksi.

generateRobots

Luo robots.txt-sisältöä: salli kaikki sekä Host- ja Sitemap-rivit. sitemapPath-arvon oletus on /sitemap.xml.

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

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

CSS-esiasetus

Tuo CSS-esiasetus kohteeseen globals.css:

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

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

@source-polut ovat suhteessa kohteeseen src/app/globals.css.

Esiasetus sisältää:

• Tailwind CSS v4 (asenna tailwindcss ja @tailwindcss/postcss itse)
• Fumadocs-neutraalin teeman
• Fumadocs-esiasetuksen tyylit
• --font-sans asetettuna kohteen FontHead määrittämään --font-inter-muuttujaan
• Inter OpenType -ominaisuudet leipätekstille ja otsikoille
• Korkean asettelun tyylit ja kohteen Onedocs asettelun hienosäädöt

MDX-komponentit

mdxComponents-vienti levittää kohteen Fumadocs UI oletus-MDX-komponentit ja lisää alla luetellut komponentit:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Sisältyvät komponentit:

• Fumadocs UI oletukset: pre (koodilohkot), a, img, h1 – h6 (ankkurilinkilliset otsikot), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout – tieto-, varoitus- ja virheilmoitukset
• Card, Cards – korttiasettelut
• Tab, Tabs – välilehdillä jaettu sisältö
• Step, Steps – numeroidut vaiheet
• Accordion, Accordions – kokoon taitettavat osiot
• File, Folder, Files – tiedostopuut
• ImageZoom – suurennettavat kuvat
• TypeTable – tyyppien dokumentaatiotaulukot

InstallBlock ja CodeBlock eivät sisälly pakettiin; lisää ne itse Components-sivulla kuvatulla tavalla.

Katso käyttöesimerkkejä Components-sivulta.