API Αναφορά

Πλήρης αναφορά για όλες τις εξαγωγές του πακέτου onedocs.

Σημεία εισόδου

Διατάξεις

DocsLayout

Περιέκτης κύριας διάταξης για σελίδες τεκμηρίωσης. Παρέχει πλευρική πλοήγηση, αναζήτηση και εναλλαγή θέματος.

import { DocsLayout } from "onedocs";

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

Ιδιότητες:

• config - Το αντικείμενο OnedocsConfig σας
• pageTree - Δέντρο σελίδων από την πηγή σας (π.χ. e.g, source.pageTree)
• children - Περιεχόμενο σελίδας

DocsPage

Περιέκτης για μεμονωμένες σελίδες τεκμηρίωσης. Τυλίγει τα Fumadocs UI DocsPage και τοποθετεί το περιεχόμενο στο 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>
  );
}

Ιδιότητες:

• toc - Πίνακας περιεχομένων από τα δεδομένα της σελίδας
• children - Περιεχόμενο MDX
• Κάθε άλλη ιδιότητα του Fumadocs UI DocsPage, όπως το full

DocsBody

Εσωτερικός περιέκτης σώματος για περιεχόμενο τεκμηρίωσης. Χρησιμοποιείται εσωτερικά από το DocsPage.

import { DocsBody } from "onedocs";

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

HomePage

Πλήρες στοιχείο σελίδας προορισμού με κύριο τμήμα, χαρακτηριστικά και υποσέλιδο.

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

Ιδιότητες:

• config - Το αντικείμενο OnedocsConfig σας
• packageName - Όνομα πακέτου για το μπλοκ εγκατάστασης (προαιρετικό)
• children - Περιεχόμενο μεταξύ των χαρακτηριστικών και του υποσέλιδου (προαιρετικό)

Δείτε τα αρχική σελίδα και υποσέλιδο για να δείτε τι ελέγχει η ρύθμιση.

HomeLayout

Βασική διάταξη αρχικής σελίδας (χρησιμοποιείται εσωτερικά από το HomePage).

import { HomeLayout } from "onedocs";

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

createBaseOptions

Δημιουργεί τις επιλογές διάταξης Fumadocs UI (τίτλος ή λογότυπο γραμμής πλοήγησης, nav.links και σύνδεσμος GitHub) από τις ρυθμίσεις σας. Τα DocsLayout και HomeLayout το χρησιμοποιούν· καλέστε το οι ίδιοι όταν αποδίδετε απευθείας μια διάταξη Fumadocs UI.

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

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

Στοιχεία

InstallBlock

Καρτέλες διαχειριστών πακέτων που εμφανίζουν εντολές εγκατάστασης για npm, yarn, pnpm και bun (npm i, yarn add, pnpm add, bun add). Είναι ασύγχρονο στοιχείο διακομιστή.

import { InstallBlock } from "onedocs";

<InstallBlock packageName="onedocs" />

Ιδιότητες:

• packageName - Το όνομα πακέτου npm προς εγκατάσταση
• title - Επικεφαλίδα πάνω από τις καρτέλες (προαιρετικό)
• description - Κείμενο πάνω από τις καρτέλες (προαιρετικό)
• children - Περιεχόμενο κάτω από τις καρτέλες (προαιρετικό)

Button

Στρογγυλεμένος σύνδεσμος με μορφοποίηση κύριου κουμπιού. Διαθέτει ένα μόνο στυλ.

import { Button } from "onedocs";

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

Ιδιότητες:

• href - Προορισμός συνδέσμου
• children - Κείμενο κουμπιού
• className - Πρόσθετες κλάσεις (προαιρετικό)

Logo

Αποδίδει μια ανοιχτή και μια σκοτεινή εικόνα και εμφανίζει εκείνη που ταιριάζει με το τρέχον θέμα. Τα DocsLayout και HomePage το χρησιμοποιούν για ένα logo με ανοιχτές και σκοτεινές παραλλαγές.

import { Logo } from "onedocs";

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

Ιδιότητες:

• light - Διαδρομή εικόνας για φωτεινή λειτουργία
• dark - Διαδρομή εικόνας για σκοτεινή λειτουργία
• alt - Εναλλακτικό κείμενο (προεπιλογή: "Logo")
• className - Κλάσεις και για τις δύο εικόνες (προαιρετικό)

CTASection

Ενότητα προτροπής για ενέργεια στην αρχική σελίδα.

import { CTASection } from "onedocs";

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

Ιδιότητες:

• title - Επικεφαλίδα ενότητας
• description - Κείμενο κάτω από την επικεφαλίδα (προαιρετικό)
• cta - Ρύθμιση κουμπιού με label και href
• children - Περιεχόμενο κάτω από το κουμπί (προαιρετικό)

FontHead

Προφορτώνει τη γραμματοσειρά Inter Variable, δηλώνει το @font-face της και την ορίζει ως γραμματοσειρά της σελίδας. Προσθέστε την στο <head> της βασικής διάταξής σας.

import { FontHead } from "onedocs";

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

Το Onedocs δεν περιλαμβάνει τη γραμματοσειρά. Από προεπιλογή, το FontHead φορτώνει το /fonts/InterVariable.woff2, επομένως τοποθετήστε το αρχείο στο public/fonts/ ή περάστε ένα διαφορετικό URL με το fontPath:

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

GitHubIcon

Στοιχείο εικονιδίου GitHub (χρησιμοποιείται εσωτερικά στην πλοήγηση).

import { GitHubIcon } from "onedocs";

<GitHubIcon className="size-5" />

CodeBlock

Μπλοκ κώδικα με επισήμανση σύνταξης, η οποία γίνεται στον διακομιστή με Shiki μέσω Fumadocs. Είναι ασύγχρονο στοιχείο διακομιστή.

import { CodeBlock } from "onedocs";

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

Διαμόρφωση

defineConfig

Βοηθητικό πρόγραμμα ρυθμίσεων με ασφάλεια τύπων.

import { defineConfig } from "onedocs/config";

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

OnedocsConfig

Τύπος TypeScript για ρυθμίσεις.

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

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

Δείτε τη Ρύθμιση για όλες τις επιλογές.

Βοηθητικά προγράμματα πηγών

loader

Επανεξαγωγή του loader fumadocs-core/source για τη δημιουργία πηγών περιεχομένου.

import { loader } from "onedocs/source";

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

createSource

Βοηθητικό πρόγραμμα για τη δημιουργία πηγής περιεχομένου (περιτύλιγμα γύρω από loader). Η βασική τιμή URL είναι από προεπιλογή /docs.

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 επιστρέφει μια πηγή χωρίς τύπο, επομένως το TypeScript αναφέρει σφάλματα, όπως το Property 'data' does not exist on type 'unknown', όταν διαβάζετε το page.data (#4). Χρησιμοποιήστε το loader όπως φαίνεται παραπάνω μέχρι να διορθωθεί αυτό.

Μεταδεδομένα

createMetadata

Δημιουργεί μεταδεδομένα Next.js για τη βασική διάταξή σας.

import { createMetadata } from "onedocs/metadata";

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

Επιλογές:

• baseUrl - Η βασική URL του ιστότοπού σας (προαιρετικό)
• additional - Πρόσθετα πεδία Metadata, που συγχωνεύονται τελευταία (προαιρετικό)

Επιστρέφει: Next.js αντικείμενο Metadata με:

• Τίτλο (config.title) και πρότυπο τίτλου (%s | Site Name)
• Περιγραφή
• Favicon από config.icon, όταν έχει οριστεί
• Όταν έχει οριστεί το baseUrl: metadataBase, μεταδεδομένα OpenGraph και κάρτα Twitter summary_large_image

createDocsPageMetadata

Δημιουργεί τα μεταδεδομένα τίτλου και περιγραφής για μια σελίδα τεκμηρίωσης. Δέχεται ένα αντικείμενο με title και ένα προαιρετικό 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,
  });
}

Για εικόνα Open Graph ανά σελίδα, δείτε τις Δυναμικές εικόνες OG.

Εικόνες OpenGraph

createRootOGImage

Δημιουργεί εικόνα OG για την αρχική σελίδα: το λογότυπό σας στο κέντρο, σε μαύρο φόντο.

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

Δημιουργεί εικόνα OG για σελίδες τεκμηρίωσης: το λογότυπο επάνω αριστερά και ο τίτλος με λευκά γράμματα σε μαύρο φόντο. Το όρισμα γραμματοσειράς είναι προαιρετικό· αν παραλειφθεί, ο τίτλος χρησιμοποιεί τη γραμματοσειρά συστήματος.

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

Δυναμικές εικόνες OG

Για εικόνες OG ανά σελίδα, σερβίρετέ τις από μια διαδρομή. Οι σελίδες δεν παραπέμπουν αυτόματα σε αυτήν τη διαδρομή: προσθέστε τη μόνοι σας στα μεταδεδομένα κάθε σελίδας, για παράδειγμα με το openGraph: { images: "/docs/og/getting-started" } δίπλα στα πεδία από το 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);
}

Βοηθητικές συναρτήσεις

Απαιτούμενα αρχεία:

• public/logo-dark.svg - Λογότυπο για εικόνες OG. Οι βοηθητικές συναρτήσεις OG καθορίζουν το μέγεθός του από τα γνωρίσματα width και height, επομένως η ετικέτα <svg> πρέπει να έχει και τα δύο ως απλούς αριθμούς.
• public/fonts/Inter-Medium.ttf - Γραμματοσειρά για τίτλους. Το Onedocs δεν την περιλαμβάνει.

LLMs.txt

Δημιουργεί αρχεία LLMs.txt για βοηθούς τεχνητής νοημοσύνης.

generateLLMsText

Δημιουργεί συνοπτικό περιεχόμενο LLMs.txt. Δέχεται μια πηγή περιτυλιγμένη με createLLMsSource και { title, description? } και επιστρέφει ένα 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 των σελίδων γράφονται όπως προέρχονται από την πηγή, για παράδειγμα /docs/getting-started, χωρίς τομέα.

generateLLMsFullText

Δημιουργεί πλήρες LLMs.txt με όλο το περιεχόμενο της σελίδας. Δέχεται μόνο την περιτυλιγμένη πηγή και επιστρέφει ένα 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" },
  });
}

Τα σώματα των σελίδων περιλαμβάνονται μόνο όταν είναι ενεργό το Fumadocs MDX του includeProcessedMarkdown· δείτε SEO & Αναζήτηση.

createLLMsSource

Περιτυλίγει μια πηγή Fumadocs (αποτέλεσμα loader() ή createSource()) στη μορφή που διαβάζουν οι δύο παραπάνω συναρτήσεις: τους φορτωτές URL, τίτλου, περιγραφής και κειμένου κάθε σελίδας.

SEO

generateSitemap

Δημιουργεί χάρτη ιστοτόπου για την τεκμηρίωσή σας. Δέχεται ένα αντικείμενο: baseUrl, τη λίστα pages (συνήθως από το meta.json) και ένα προαιρετικό docsPath (προεπιλογή /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 ?? [],
  });
}

Δείτε το SEO & Αναζήτηση για να μάθετε πώς οι καταχωρίσεις γίνονται URL.

generateRobots

Δημιουργεί περιεχόμενο robots.txt: επιτρέπει τα πάντα, καθώς και γραμμές Host και Sitemap. Το sitemapPath έχει προεπιλεγμένη τιμή /sitemap.xml.

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

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

Προκαθορισμένη ρύθμιση CSS

Εισαγάγετε την προκαθορισμένη ρύθμιση CSS στο globals.css σας:

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

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

Οι διαδρομές @source είναι σχετικές με το src/app/globals.css.

Η προκαθορισμένη ρύθμιση περιλαμβάνει:

• Tailwind CSS v4 (εγκαταστήστε μόνοι σας τα tailwindcss και @tailwindcss/postcss)
• Ουδέτερο θέμα Fumadocs
• Στυλ προκαθορισμένης ρύθμισης Fumadocs
• Το --font-sans ορίζεται στη μεταβλητή --font-inter που ορίζει το FontHead
• Χαρακτηριστικά OpenType της Inter για το κυρίως κείμενο και τις επικεφαλίδες
• Στυλ διάταξης πλήρους ύψους και προσαρμογές διάταξης Onedocs

Στοιχεία MDX

Η εξαγωγή mdxComponents επεκτείνει τα προεπιλεγμένα στοιχεία Fumadocs UI MDX και προσθέτει τα παρακάτω στοιχεία:

import { mdxComponents } from "onedocs";

<MDX components={mdxComponents} />

Περιλαμβανόμενα στοιχεία:

• Προεπιλογές Fumadocs UI: pre (μπλοκ κώδικα), a, img, h1 έως h6 (επικεφαλίδες με αγκυρώσεις), table, CodeBlockTab, CodeBlockTabs, CodeBlockTabsList, CodeBlockTabsTrigger, CalloutContainer, CalloutTitle, CalloutDescription
• Callout - Πλαίσια ενημέρωσης/προειδοποίησης/σφάλματος
• Card, Cards - Διατάξεις καρτών
• Tab, Tabs - Περιεχόμενο με καρτέλες
• Step, Steps - Αριθμημένα βήματα
• Accordion, Accordions - Συμπτυσσόμενες ενότητες
• File, Folder, Files - Δέντρα αρχείων
• ImageZoom - Εικόνες με δυνατότητα μεγέθυνσης
• TypeTable - Πίνακες τεκμηρίωσης τύπων

Τα InstallBlock και CodeBlock δεν περιλαμβάνονται· προσθέστε τα μόνοι σας όπως φαίνεται στα Στοιχεία.

Δείτε τα Στοιχεία για παραδείγματα χρήσης.