API-referens

Fullständig referens för alla exporter från paketet onedocs.

Ingångspunkter

Layouter

DocsLayout

Huvudlayoutomslag för dokumentationssidor. Tillhandahåller sidonavigering, sökning och temaväxling.

import { DocsLayout } from "onedocs";

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

Egenskaper:

• config - Ditt OnedocsConfig-objekt
• pageTree - Sidträd från din källa (e.g t.ex. source.pageTree)
• children - Sidinnehåll

DocsPage

Omslag för enskilda dokumentationssidor. Omsluter Fumadocs UI DocsPage och placerar innehållet i 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>
  );
}

Egenskaper:

• toc - Innehållsförteckning från siddata
• children - Innehåll i MDX
• Alla andra egenskaper för Fumadocs UI DocsPage, till exempel full

DocsBody

Inre omslag för dokumentationsinnehåll. Används internt av DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Fullständig landningssidakomponent med huvudsektion, funktioner och sidfot.

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

Egenskaper:

• config - Ditt OnedocsConfig-objekt
• packageName - Paketnamn för installationsblock (valfritt)
• children - Innehåll mellan funktionerna och sidfoten (valfritt)

Se startsida och sidfot för information om vad konfigurationen styr.

HomeLayout

Baslayout för startsidan (används internt av HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Skapar layoutalternativen för Fumadocs UI (navigeringsfältets titel eller logotyp, nav.links och länken GitHub) från din konfiguration. DocsLayout och HomeLayout använder den; anropa den själv när du återger en layout av typen Fumadocs UI direkt.

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

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

Komponenter

InstallBlock

Flikar för pakethanterare med installationskommandon för npm, yarn, pnpm och bun (npm i, yarn add, pnpm add, bun add). Det är en asynkron serverkomponent.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Egenskaper:

• packageName - Paketnamnet för npm som ska installeras
• title - Rubrik ovanför flikarna (valfritt)
• description - Text ovanför flikarna (valfritt)
• children - Innehåll under flikarna (valfritt)

Button

Rundad länk utformad som en primärknapp. Det finns en enda stil.

import { Button } from "onedocs";

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

Egenskaper:

• href - Länkmål
• children - Knapptext
• className - Extra klasser (valfritt)

Logo

Återger en ljus och en mörk bild och visar den som matchar det aktuella temat. DocsLayout och HomePage använder den för en logo med ljusa och mörka varianter.

import { Logo } from "onedocs";

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

Props:

• light - Bildsökväg för ljust läge
• dark - Bildsökväg för mörkt läge
• alt - Alt-text (standard: "Logo")
• className - Klasser för båda bilderna (valfritt)

CTASection

Uppmaningssektion för startsidan.

import { CTASection } from "onedocs";

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

Props:

• title - Sektionsrubrik
• description - Text under rubriken (valfritt)
• cta - Knappkonfiguration med label och href
• children - Innehåll under knappen (valfritt)

FontHead

Förladdar typsnittet Inter Variable, deklarerar dess @font-face och anger det som sidans typsnitt. Lägg till det i rotlayoutens <head>.

import { FontHead } from "onedocs";

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

Onedocs levereras inte med typsnittet. Som standard läser FontHead in /fonts/InterVariable.woff2, så placera filen i public/fonts/ eller skicka med ett annat URL med fontPath:

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

GitHubIcon

GitHub-ikonkomponent (används internt i navigeringen).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Kodblock med syntaxmarkering, markerat på servern med Shiki via Fumadocs. Det är en asynkron serverkomponent.

import { CodeBlock } from "onedocs";

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

Konfiguration

defineConfig

Typsäker konfigurationshjälpare.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

TypeScript-typ för konfiguration.

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

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

Se Configuration för alla alternativ.

Källverktyg

loader

Återexport av fumadocs-core/source-laddaren för att skapa innehållskällor.

import { loader } from "onedocs/source";

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

createSource

Hjälpare för att skapa en innehållskälla (omslag runt laddaren). Basvärdet för URL är /docs.

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

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

I 0.1.27 returnerar createSource en otypad källa, så TypeScript rapporterar fel som Property 'data' does not exist on type 'unknown' när du läser page.data (#4). Använd loader enligt exemplet ovan tills det är åtgärdat.

Metadata

createMetadata

Genererar Next.js-metadata för din rotlayout.

import { createMetadata } from "onedocs/metadata";

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

Alternativ:

• baseUrl - Webbplatsens bas-URL (valfritt)
• additional - Extra Metadata-fält, sammanfogade sist (valfritt)

Returnerar: objektet Next.js Metadata med:

• Titel (config.title) och titelmall (%s | Site Name)
• Beskrivning
• Favicon från config.icon, om det är angivet
• När baseUrl är angivet: metadataBase, OpenGraph-metadata och ett Twitter summary_large_image-kort

createDocsPageMetadata

Genererar titel- och beskrivningsmetadata för en dokumentationssida. Den tar ett objekt med title och ett valfritt 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,
  });
}

För en Open Graph-bild per sida, se Dynamic OG Images.

OpenGraph-bilder

createRootOGImage

Skapar en OG-bild för startsidan: din logotyp centrerad på svart bakgrund.

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

Skapar en OG-bild för dokumentationssidor: logotypen uppe till vänster och titeln i vitt på svart bakgrund. Typsnittsargumentet är valfritt; utan det används systemets typsnitt för titeln.

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

Dynamiska OG-bilder

För OG-bilder per sida, visa dem från en route. Inget kopplar automatiskt sidorna till denna route: lägg själv till den i varje sidas metadata, till exempel med openGraph: { images: "/docs/og/getting-started" } bredvid fälten från 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);
}

Hjälpfunktioner

Obligatoriska filer:

• public/logo-dark.svg - Logotyp för OG-bilder. OG-hjälpfunktionerna hämtar storleken från dess attribut width och height, så <svg>-taggen måste ha båda som vanliga tal.
• public/fonts/Inter-Medium.ttf - Typsnitt för titlar. Onedocs levereras inte med det.

LLMs.txt

Generera LLMs.txt-filer för AI-assistenter.

generateLLMsText

Genererar kortfattat LLMs.txt-innehåll. Tar en källa omsluten med createLLMsSource och { title, description? } och returnerar ett 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" },
  });
}

Sidans URL:er skrivs som de kommer från källan, till exempel /docs/getting-started, utan domän.

generateLLMsFullText

Genererar fullständigt LLMs.txt med komplett sidinnehåll. Tar endast den omslutna källan och returnerar ett 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" },
  });
}

Sidornas innehåll tas bara med när Fumadocs MDXs includeProcessedMarkdown är aktiverat; se SEO och sök.

createLLMsSource

Omsluter en Fumadocs-källa (resultat från loader() eller createSource()) i den form som de två funktionerna ovan läser: varje sidas URL, titel, beskrivning och textladdare.

SEO

generateSitemap

Genererar en webbplatskarta för din dokumentation. Tar ett objekt: baseUrl, listan med pages (vanligtvis från meta.json) och ett valfritt docsPath (standard /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 ?? [],
  });
}

Se SEO och sök för hur poster blir URL:er.

generateRobots

Genererar robots.txt-innehåll: tillåter allt, plus raderna Host och Sitemap. sitemapPath har standardvärdet /sitemap.xml.

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

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

Förinställningen CSS

Importera förinställningen CSS i din globals.css:

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

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

Sökvägarna @source är relativa till src/app/globals.css.

Förinställningen innehåller:

• Tailwind CSS v4 (installera tailwindcss och @tailwindcss/postcss själv)
• Fumadocs neutralt tema
• Fumadocs-förinställningsstilar
• --font-sans inställt på variabeln --font-inter som FontHead definierar
• Inter OpenType-funktioner för brödtext och rubriker
• Layoutstilar med full höjd och justeringarna för layouten Onedocs

Komponenter för MDX

Exporten mdxComponents sprider standardkomponenterna Fumadocs UI MDX och lägger till komponenterna nedan:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Komponenter som ingår:

• Standardkomponenter för Fumadocs UI: pre (kodblock), a, img, h1 till h6 (rubriker med ankare), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Informations-, varnings- och felrutor
• Card, Cards - Kortlayouter
• Tab, Tabs - Flikinnehåll
• Step, Steps - Numrerade steg
• Accordion, Accordions - Utfällbara sektioner
• File, Folder, Files - Filträd
• ImageZoom - Zoomningsbara bilder
• TypeTable - Tabeller med typdokumentation

InstallBlock och CodeBlock ingår inte; lägg till dem själv enligt exemplet i Components.

Se Components för användningsexempel.