Référence API

Référence complète de tous les exports du package onedocs.

Points d’entrée

Mises en page

DocsLayout

Conteneur de mise en page principal des pages de documentation. Il fournit une navigation latérale, une recherche et un sélecteur de thème.

import { DocsLayout } from "onedocs";

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

Propriétés :

• config - Votre objet OnedocsConfig
• pageTree - Arborescence des pages de votre source (e.g., source.pageTree)
• children - Contenu de la page

DocsPage

Conteneur pour les pages de documentation individuelles. Il enveloppe le Fumadocs UI DocsPage et place le contenu dans 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>
  );
}

Propriétés :

• toc - Table des matières issue des données de la page
• children - Contenu MDX
• Toute autre propriété de Fumadocs UI DocsPage, telle que full

DocsBody

Conteneur interne du corps du contenu de la documentation. Utilisé en interne par DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Composant complet de page d’accueil avec une section principale, des fonctionnalités et un pied de page.

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

Propriétés :

• config - Votre objet OnedocsConfig
• packageName - Nom du package pour le bloc d’installation (facultatif)
• children - Contenu entre les fonctionnalités et le pied de page (facultatif)

Consultez la page d’accueil et le pied de page pour savoir ce que contrôle la configuration.

HomeLayout

Mise en page de base de la page d’accueil (utilisée en interne par HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Génère les options de mise en page de Fumadocs UI (titre ou logo de la barre de navigation, nav.links et lien GitHub) à partir de votre configuration. DocsLayout et HomeLayout les utilisent ; appelez cette fonction vous-même lorsque vous affichez directement une mise en page Fumadocs UI.

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

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

Composants

InstallBlock

Onglets de gestionnaires de packages affichant les commandes d’installation pour npm, yarn, pnpm et bun (npm i, yarn add, pnpm add, bun add). Il s’agit d’un composant serveur asynchrone.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Propriétés :

• packageName - Nom du package npm à installer
• title - Titre au-dessus des onglets (facultatif)
• description - Texte au-dessus des onglets (facultatif)
• children - Contenu sous les onglets (facultatif)

Button

Lien arrondi présenté comme un bouton principal. Un seul style est disponible.

import { Button } from "onedocs";

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

Propriétés :

• href - Destination du lien
• children - Texte du bouton
• className - Classes supplémentaires (facultatif)

Logo

Affiche une image claire et une image sombre, puis montre celle qui correspond au thème actuel. DocsLayout et HomePage l’utilisent pour un logo avec des variantes claires et sombres.

import { Logo } from "onedocs";

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

Props :

• light - Chemin de l’image pour le mode clair
• dark - Chemin de l’image pour le mode sombre
• alt - Texte alternatif (par défaut : "Logo")
• className - Classes pour les deux images (facultatif)

CTASection

Section d’appel à l’action pour la page d’accueil.

import { CTASection } from "onedocs";

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

Props :

• title - Titre de la section
• description - Texte sous le titre (facultatif)
• cta - Configuration du bouton avec label et href
• children - Contenu sous le bouton (facultatif)

FontHead

Précharge la police Inter Variable, déclare son @font-face et la définit comme police de la page. Ajoutez-la au <head> de votre mise en page racine.

import { FontHead } from "onedocs";

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

Onedocs ne fournit pas la police. Par défaut, FontHead charge /fonts/InterVariable.woff2 ; placez donc le fichier dans public/fonts/, ou transmettez un autre URL avec fontPath :

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

GitHubIcon

Composant d’icône GitHub (utilisé en interne dans la navigation).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Bloc de code avec coloration syntaxique, coloré sur le serveur avec Shiki via Fumadocs. Il s’agit d’un composant serveur asynchrone.

import { CodeBlock } from "onedocs";

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

Configuration

defineConfig

Assistant de configuration à types sûrs.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Type TypeScript pour la configuration.

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

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

Consultez Configuration pour voir toutes les options.

Utilitaires de source

loader

Réexportation du chargeur fumadocs-core/source pour créer des sources de contenu.

import { loader } from "onedocs/source";

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

createSource

Assistant de création d’une source de contenu (encapsulation du chargeur). La base URL est /docs par défaut.

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

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

Dans 0.1.27, createSource renvoie une source non typée ; TypeScript signale donc des erreurs telles que Property 'data' does not exist on type 'unknown' lorsque vous lisez page.data (#4). Utilisez loader comme indiqué ci-dessus jusqu’à ce que le problème soit résolu.

Métadonnées

createMetadata

Génère les métadonnées Next.js pour votre mise en page racine.

import { createMetadata } from "onedocs/metadata";

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

Options :

• baseUrl - URL de base de votre site URL (facultatif)
• additional - Champs Metadata supplémentaires, fusionnés en dernier (facultatif)

Renvoie : un objet Next.js Metadata avec :

• Titre (config.title) et modèle de titre (%s | Site Name)
• Description
• Icône de favori provenant de config.icon, si défini
• Si baseUrl est défini : metadataBase, métadonnées OpenGraph et carte Twitter summary_large_image

createDocsPageMetadata

Génère les métadonnées de titre et de description d’une page de documentation. Prend un objet avec title et un description facultatif.

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

Pour une image Open Graph propre à une page, consultez Images OG dynamiques.

Images OpenGraph

createRootOGImage

Crée une image OG pour la page d’accueil : votre logo centré sur un fond noir.

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

Crée une image OG pour les pages de documentation : le logo en haut à gauche et le titre en blanc sur fond noir. L’argument de police est facultatif ; sans lui, le titre utilise la police système.

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

Images OG dynamiques

Pour les images OG propres à chaque page, servez-les depuis une route. Aucune page ne pointe automatiquement vers cette route : ajoutez-la vous-même aux métadonnées de chaque page, par exemple avec openGraph: { images: "/docs/og/getting-started" } à côté des champs de 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);
}

Fonctions d’assistance

Fichiers requis :

• public/logo-dark.svg - Logo pour les images OG. Les fonctions d’assistance OG le dimensionnent à partir de ses attributs width et height ; la balise <svg> doit donc contenir les deux sous forme de nombres simples.
• public/fonts/Inter-Medium.ttf - Police pour les titres. Onedocs ne la fournit pas.

LLMs.txt

Générer des fichiers LLMs.txt pour les assistants IA.

generateLLMsText

Génère un contenu LLMs.txt concis. Prend une source encapsulée avec createLLMsSource et { title, description? }, et renvoie une promesse.

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

Les URL des pages sont reprises telles quelles depuis la source, par exemple /docs/getting-started, sans domaine.

generateLLMsFullText

Génère un LLMs.txt complet avec le contenu intégral des pages. Prend uniquement la source encapsulée et renvoie une promesse.

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

Le corps des pages est inclus uniquement si Fumadocs de MDX a la valeur includeProcessedMarkdown ; consultez SEO et recherche.

createLLMsSource

Encapsule une source Fumadocs (résultat loader() ou createSource()) dans la structure attendue par les deux fonctions ci-dessus : le URL de chaque page, son titre, sa description et ses chargeurs de texte.

SEO

generateSitemap

Génère un plan de site pour votre documentation. Prend un objet avec baseUrl, la liste pages (généralement issue de meta.json) et un docsPath facultatif (par défaut /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 ?? [],
  });
}

Consultez SEO et recherche pour savoir comment les entrées deviennent des URL.

generateRobots

Génère du contenu robots.txt : tout autoriser, plus les lignes Host et Sitemap. sitemapPath est défini par défaut sur /sitemap.xml.

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

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

Préréglage CSS

Importez le préréglage CSS dans votre globals.css :

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

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

Les chemins @source sont relatifs à src/app/globals.css.

Le préréglage comprend :

• Tailwind CSS v4 par défaut (installez vous-même tailwindcss et @tailwindcss/postcss)
• Thème neutre Fumadocs
• Styles du préréglage Fumadocs
• --font-sans défini sur la variable --font-inter définie par FontHead
• Fonctionnalités OpenType d’Inter pour le corps du texte et les titres
• Styles de mise en page pleine hauteur et ajustements de mise en page Onedocs

Composants MDX

L’export mdxComponents étend les composants par défaut Fumadocs UI MDX et ajoute les composants ci-dessous :

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Composants inclus :

• Valeurs par défaut de Fumadocs UI : pre (blocs de code), a, img, de h1 à h6 (titres avec ancres), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Encadrés d’information, d’avertissement et d’erreur
• Card, Cards - Mises en page en cartes
• Tab, Tabs - Contenu à onglets
• Step, Steps - Étapes numérotées
• Accordion, Accordions - Sections repliables
• File, Folder, Files - Arborescences de fichiers
• ImageZoom - Images avec zoom
• TypeTable - Tableaux de documentation des types

InstallBlock et CodeBlock ne sont pas inclus ; ajoutez-les vous-même comme indiqué dans Composants.

Consultez Composants pour des exemples d’utilisation.