Konfiguration

Visa som Markdown Redigera på GitHub Dokumentation på 7b38e05

Inställningar för hela webbplatsen finns i onedocs.config.ts i projektroten. Skicka det exporterade objektet till DocsLayout, HomePage och createMetadata, som läser in det. Var innehållet finns anges i source.config.ts, inte här (se Komma igång).

Grundläggande konfiguration

TypeScript

import { defineConfig } from "onedocs/config";

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

Det är allt som krävs. Allt annat är valfritt.

Fullständigt exempel

Funktionsikoner är React-element, så en konfiguration som använder dem måste vara 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" }],
  },
});

Alternativ

title (obligatoriskt)

Webbplatsens namn. Navigeringsfältet visar det när inget logo har angetts, createMetadata använder det som standardtitel för sidan och i mallen %s | Title, och startsidan använder det som huvudrubrik och i upphovsrättsraden i sidfoten.

TypeScript

title: "My Project"

description

Kort beskrivning. createMetadata använder den som metabeskrivning, och startsidan visar den under huvudrubriken när homepage.hero.description inte har angetts.

TypeScript

description: "Documentation for My Project"

logo

Ersätter titeln i navigeringsfältet. Använd en enda sökväg eller varianter för ljust och mörkt läge; bilden är 24 px hög och använder title som alt-text.

TypeScript

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

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

ikon

Faviconen anges via createMetadata. Varianter för ljust och mörkt läge visas med prefers-color-scheme-mediefrågor.

TypeScript

icon: "/icon.png"

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

nav

Konfiguration av navigeringsfältet, som används av DocsLayout och 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",
}

homepage

Huvudsektionen och funktionsrutnätet som HomePage renderar.

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 renderas som det är, så skicka med ett element, till exempel en ikon från lucide-react. En sträng som "rocket" skrivs ut som text.

Ytterligare två alternativ för huvudsektionen ersätter delar av standardinnehållet:

hero.left ersätter titeln, beskrivningen, installationsblocket och knappen med eget innehåll. Den tar en React-nod eller en funktion som returnerar en sådan.
hero.right fyller den högra halvan av huvudsektionen. Den döljs under brytpunkten lg.

Länkar och sociala ikoner i sidfoten HomePage, bredvid upphovsrättsraden. Båda öppnas i en ny flik.

TSX

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

Varje social länk använder label som tillgängligt namn.

Alternativ som ännu inte har någon effekt

OnedocsConfig typbestämmer också docs, theme och i18n, och defineConfig fyller i standardvärden för docs.dir och theme.darkMode, men ingen kod i Onedocs läser in dem (#2). Det händer ingenting när du anger dem:

docs.dir: innehållsmappen är den dir du skickar till defineDocs i source.config.ts.
theme.primaryColor och theme.darkMode: färgerna kommer från temat Fumadocs UI som importeras av förinställningen CSS, och ljust och mörkt läge kommer från Fumadocs UIs RootProvider.
i18n: Onedocs saknar stöd för flera språk.

TypeScript

Hjälparen defineConfig ger dig fullständig automatisk komplettering:

TypeScript

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

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

export default defineConfig(config);

defineConfig returnerar objektet du skickar med, plus de oanvända standardvärdena docs och theme som beskrivs ovan.