Konfiguration

Vis som Markdown Rediger på GitHub Dokumentation hos 7b38e05

Indstillinger for hele webstedet placeres i onedocs.config.ts i projektets rodmappe. Du videregiver det eksporterede objekt til DocsLayout, HomePage og createMetadata, som læser det. Placeringen af dit indhold angives i source.config.ts, ikke her (se Kom godt i gang).

Grundlæggende opsætning

TypeScript

import { defineConfig } from "onedocs/config";

export default defineConfig({
  title: "My Project",
  description: "Documentation for My Project",
});

Det er det minimale. Alt andet er valgfrit.

Fuldt eksempel

Funktionsikoner er React-elementer, så en konfiguration, der bruger dem, skal være en .tsx-fil:

TSX

import { defineConfig } from "onedocs/config";
import { Rocket, Zap } from "lucide-react";

export default defineConfig({
  title: "My Project",
  description: "Documentation for My Project",

  // Logo (string or light/dark variants)
  logo: "/logo.svg",
  // logo: { light: "/logo-light.svg", dark: "/logo-dark.svg" },

  // Favicon (string or light/dark variants), used by createMetadata
  icon: "/icon.png",

  // Navigation bar
  nav: {
    links: [
      { label: "Blog", href: "/blog" },
      { label: "Changelog", href: "/changelog" },
    ],
    github: "username/repo",
  },

  // Homepage
  homepage: {
    hero: {
      title: "My Project",
      description: "Documentation that ships with the code",
      cta: { label: "Get Started", href: "/docs" },
    },
    features: [
      {
        title: "Fast",
        description: "Static pages built by Next.js",
        icon: <Zap className="size-5 text-fd-primary" />,
      },
      {
        title: "Simple",
        description: "Write markdown, get docs",
        icon: <Rocket className="size-5 text-fd-primary" />,
      },
    ],
  },

  // Homepage footer
  footer: {
    links: [{ label: "License", href: "https://github.com/username/repo/blob/main/LICENSE" }],
  },
});

Indstillinger

title (påkrævet)

Navnet på dit websted. Navbar'en viser det, når der ikke er angivet noget logo, createMetadata bruger det som standard sidetitel og i skabelonen %s | Title, og forsiden bruger det som hero-titel og i footeren på ophavsretslinjen.

TypeScript

title: "My Project"

description

Kort beskrivelse. createMetadata bruger den som metabeskrivelse, og forsiden viser den under hero-titlen, når homepage.hero.description ikke er angivet.

TypeScript

description: "Documentation for My Project"

logo

Erstatter titlen i navbar'en. Brug én sti eller lyse og mørke varianter; billedet er 24 px højt og bruger title som alternativ tekst.

TypeScript

// Single logo
logo: "/logo.svg"

// Light/dark mode
logo: {
  light: "/logo-light.svg",
  dark: "/logo-dark.svg"
}

ikon

Favikonen, der angives via createMetadata. Lyse og mørke varianter leveres med prefers-color-scheme-medieforespørgsler.

TypeScript

icon: "/icon.png"

// Light/dark mode
icon: {
  light: "/icon-light.png",
  dark: "/icon-dark.png"
}

navigation

Konfiguration af navigationslinjen, brugt af DocsLayout og HomePage.

TypeScript

nav: {
  // Extra links in the navbar
  links: [
    { label: "Blog", href: "/blog" },
    { label: "API", href: "/api" },
  ],

  // GitHub repo as "owner/name" (adds an icon link to https://github.com/owner/name)
  github: "username/repo",
}

startside

Hero-sektionen og funktionsgitteret, som HomePage gengiver.

TSX

homepage: {
  hero: {
    title: "My Project",        // Defaults to config.title
    description: "Description", // Defaults to config.description
    cta: {
      label: "Get Started",     // Default: "Get Started"
      href: "/docs",            // Default: "/docs"
    },
  },
  features: [
    {
      title: "Feature 1",
      description: "Description of feature 1",
      icon: <Rocket className="size-5" />, // Optional React element
    },
  ],
}

icon gengives, som den er angivet, så send et element som f.eks. et lucide-react-ikon. En streng som "rocket" udskrives som tekst.

To andre hero-indstillinger erstatter dele af standardheroen:

hero.left erstatter titlen, beskrivelsen, installationsblokken og knappen med dit eget indhold. Den tager en React-node eller en funktion, der returnerer en.
hero.right udfylder højre halvdel af heroen. Den er skjult under lg-breakpointet.

Links og sociale ikoner i sidefoden på HomePage, ved siden af copyrightlinjen. Begge åbnes i en ny fane.

TSX

// import { GitHubIcon } from "onedocs";
footer: {
  links: [{ label: "Privacy", href: "/privacy" }],
  socials: [
    { label: "GitHub", href: "https://github.com/username/repo", icon: <GitHubIcon /> },
  ],
}

Hvert socialt link bruger label som tilgængeligt navn.

Indstillinger, der endnu ikke har nogen effekt

OnedocsConfig angiver også typer for docs, theme og i18n, og defineConfig udfylder standardværdier for docs.dir og theme.darkMode, men ingen kode i Onedocs læser dem (#2). Det ændrer ikke noget at angive dem:

docs.dir: indholdsmappen er den dir, du sender til defineDocs i source.config.ts.
theme.primaryColor og theme.darkMode: farverne kommer fra temaet Fumadocs UI, som forudindstillingen CSS importerer, og lys og mørk tilstand kommer fra Fumadocs UIs RootProvider.
i18n: Onedocs understøtter ikke flere sprog.

TypeScript

Hjælpefunktionen defineConfig giver dig fuldførelse af kode:

TypeScript

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

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

export default defineConfig(config);

defineConfig returnerer det objekt, du sender, samt standardværdierne docs og theme, der ikke bruges, som beskrevet ovenfor.