Product Logo

Menü

Kern-Nextra-Theme-Bibliothek

@document-writing-tools/kernux-nextra-theme

Übersicht

Die Kern-Nextra-Theme-Bibliothek ist ein Nextra-Theme auf Basis des Kernux Design Systems. Sie dient dazu, in eigenen Next.js/Nextra-Projekten schnell konsistente, barrierearme und wartbare Dokumentationsseiten aufzubauen.

Das Paket bündelt dafür ein vorkonfiguriertes Layout, Navigationselemente, TOC, Suchintegration, Feedback-Formular sowie erweiterbare UI-Komponenten und bildet damit die technische Grundlage für den Developer Mode.

Voraussetzungen

  • Node.js und npm
  • Zugriff auf die DWT Registry
  • Ein Nextra/Next.js Projekt (oder ein mit markdown-webbook erzeugtes Template)

1) DWT Registry konfigurieren und Pakete installieren

Lege im Projekt eine .npmrc an (oder ergänze sie):

echo "@document-writing-tools:registry=https://gitlab.opencode.de/api/v4/projects/2542/packages/npm/" >> .npmrc

Installiere die Theme-Bibliothek (inkl. React-Komponenten):

npm install @document-writing-tools/kernux-nextra-theme @document-writing-tools/kernux-react

2) Theme in Next.js/Nextra konfigurieren

next.config.mjs

Die Integration erfolgt über withMarkdownWebBook:

import { withMarkdownWebBook } from '@document-writing-tools/kernux-nextra-theme/withMarkdownWebBook'
 
const config = withMarkdownWebBook({
  trailingSlash: true,
  output: exportType,
  eslint: {
    ignoreDuringBuilds: true,
  },
  compiler: {
    removeConsole: false, // Keep console output in production
  },
  webpack: (config) => {
    config.resolve.fallback = { fs: false }
    return config
  },
  basePath: process.env.BASE_PATH,
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'gitlab.com',
        pathname: '/uploads/*',
        port: '',
      },
    ],
    unoptimized: exportType === 'export',
  },
  // additional Next.js options
})
 
export default config

theme.config.tsx

Füge diese Datei im Root-Folder deines Projekts hinzu:

import { KernuxThemeConfig } from '@document-writing-tools/kernux-nextra-theme'
import { Footer } from '@document-writing-tools/kernux-nextra-theme/components'
import { Logo } from '@document-writing-tools/kernux-nextra-theme/components/logo'
 
const config: Partial<KernuxThemeConfig> = {
  // Branding properties
  logo: <Logo width={100} height={50} />,
  logoText: 'Name deines Projekts',
 
  // Header/footer visibility
  umbrellaHeader: true,
  umbrellaFooter: false,
 
  // Footer configuration (required for proper rendering)
  footer: {
    component: Footer,
    links: [
      // Example footer links - organized by column
      {
        name: 'Kontakt',
        href: '/kontakt',
        column: 'Organisation'
      },
      {
        name: 'Datenschutz',
        href: '/datenschutz',
        column: 'Rechtliches'
      },
      {
        name: 'Nutzungsbedingungen',
        href: '/nutzungsbedingungen',
        column: 'Rechtliches'
      }
    ],
    description: (
      <p className="text-sm opacity-75 max-w-md">
        Hier steht die Beschreibung deines Projekts. Erläutere kurz den Zweck und den Mehrwert.
      </p>
    ),
    copyright: (
      <p className="text-sm opacity-75">
        &copy; {new Date().getFullYear()} Name deiner Organisation. Alle Rechte vorbehalten.
      </p>
    )
  },
 
  // Accessibility options (optional, but recommended)
  accessibilityLanguages: {
    leichteSpracheHref: '/leichte-sprache', // Easy language version
    gebaerdenSprachenHref: '/gebaerdensprache' // Sign language version
  },
 
  // Search configuration
  disableSearch: false,
 
  // Navigation configuration
  hidePrimaryMenu: false,
 
  // Glossary page (if glossary feature is used)
  glossaryPage: '/glossar',
 
  // Additional optional properties you can configure:
  // header: {
  //   lowerBadgeLogoPath: '/path-to-badge-logo.svg'
  // },
  // faviconGlyph: '📚',
  // docsRepositoryBase: 'https://gitlab.com/your-org/your-project',
  // }
}
 
export default config

Hauptmerkmale dieser Vorlage:

  1. Vollständige Branding-Konfiguration: Enthält Logo, Logo-Text und Logo-Verlinkung
  2. Vollständig konfigurierter Footer: Mit strukturierten Links in Spalten, Beschreibung und Copyright
  3. Barrierefreiheits-Unterstützung: Links zu Leichter Sprache und Gebärdensprache
  4. Suche aktiviert: Standardmäßig aktiv (kann bei Bedarf deaktiviert werden)
  5. Navigation vorbereitet: Primärmenü ist standardmäßig sichtbar
  6. Glossar-Unterstützung: Vorbereiteter Pfad zur Glossar-Seite

Enthaltene erforderliche Eigenschaften:

  • logo – Branding-Element für den Header
  • logoText – Text neben dem Logo
  • logoLink – Klickverhalten des Logos
  • footer.component – Footer-Komponente
  • footer.links – Navigationslinks
  • footer.description – Footer-Beschreibung
  • footer.copyright – Copyright-Information

Optional, aber empfohlen:

  • accessibilityLanguages – Für Barrierefreiheits-Anforderungen
  • umbrellaHeader/umbrellaFooter – Zur Steuerung der Sichtbarkeit von Header/Footer
  • glossaryPage – Falls die Glossar-Funktion genutzt wird

Hinweis: Für den Start reicht eine minimale Konfiguration ohne Pflichtfelder. Alle Theme-Optionen können optional und schrittweise ergänzt werden.

3) Feedback-Komponente konfigurieren

Seit Version 1.5.x nutzt die Feedback-Funktion eine erweiterte Konfiguration. Wenn du Feedback über das Theme aktivieren willst, konfigurierst du den Block feedback in der theme.config.tsx.

import { KernuxThemeConfig } from '@document-writing-tools/kernux-nextra-theme'
 
const config: Partial<KernuxThemeConfig> = {
  // ... other theme configurations ...
  feedback: {
    // Required configuration:
    feedbackServerUrl: 'https://deine-feedback-api.beispiel.de',
    gitlabProjectId: 'deine-projekt-id',
    labels: ['dokumentation', 'feedback', 'nutzer-feedback'],
    requiredText: 'Pflichtfelder sind mit * markiert',
    privacyConsent: {
        textBeforeLink: 'Ich stimme der ',
        link: {
            label: 'Datenschutzerklärung',
            href: '/datenschutz'
        },
        textAfterLink: ' und der Datenverarbeitung zu.'
    },
    // Post-submission messages:
    afterSubmit: {
        successText: 'Vielen Dank für dein Feedback! Wir schätzen deinen Beitrag.',
        errorText: 'Beim Senden deines Feedbacks ist ein Fehler aufgetreten. Bitte versuche es erneut.',
        buttonLabel: 'Feedback anzeigen' // Optional button for non-confidential issues
    },
 
    // Optional but recommended configuration:
    headline: 'Hilf uns, diese Dokumentation zu verbessern',
    description: 'Dein Feedback hilft uns, unsere Dokumentation für alle besser zu machen.',
    buttonText: 'Feedback senden',
 
    // Field configuration (required):
    // You can define fields ordered as you like. 
    fields: {
        // The "email" and "message" fields are required by the component.
        // required fields:
        email: {
            label: 'Deine E-Mail-Adresse',
            placeholder: 'max.mustermann@beispiel.de',
            required: false, // optional, default: true
            type: 'email' // optional, input type (text, email, etc.)
        },
        message: {
            label: 'Dein Feedback',
            placeholder: 'Was können wir verbessern? Was war hilfreich?',
        },
        // additional fields (you can add custom fields here):
        name: {
            label: 'Name',
            placeholder: 'Dein Name',
            required: false,
        }
    },
 
    // Confidential issue handling:
    shouldCreateConfidentialIssue: true, // optional, default: false
 
    // Notice block (optional, shown when shouldCreateConfidentialIssue is false)
    notice: {
      title: 'Öffentliches Feedback',
      body: 'Dein Feedback ist öffentlich sichtbar und kann offen diskutiert werden. Für sensible Informationen ',
      link: {
        href: '/contact',
        label: 'kontaktiere uns direkt'
      }
    },
 
    // Custom styling props (optional):
    className: 'max-w-2xl mx-auto py-12',
    headlineClassName: 'text-2xl font-bold text-blue-600 mb-4',
    descriptionClassName: 'text-gray-600 mb-8',
    inputClassName: 'border-2 border-gray-300 rounded-lg p-3 w-full',
    inputLabelClassName: 'font-semibold text-gray-700 mb-2 block',
    textareaClassName: 'min-h-[150px] border-2 border-gray-300 rounded-lg p-3 w-full',
    checkboxClassName: 'rounded border-gray-400 mr-2',
    btnClassName: 'bg-blue-600 hover:bg-blue-700 text-white px-6 py-3 rounded-lg mt-4'
  }
  // ... other theme configurations ...
}
 
export default config

Zusätzliche Felder, Notice-Block, confidential issues und Klassen für Custom Styling können optional ergänzt werden.

Details zur Komponente findest du im Bereich Feedback.

4) Theme anpassen (wichtige Konfigurationsbereiche)

  • Header: header, umbrellaHeader, logo, logoText
  • Navigation: primaryMenu, hidePrimaryMenu, sidebar
  • Footer: footer, umbrellaFooter
  • Suche: disableSearch
  • Edit-Link: editPage
  • Feedback: feedback

5) Single-Language vs Multi-Language

Single-Language

Nutze nur eine Sprache (z. B. Deutsch) und halte URLs/Content ausschließlich in dieser Sprache.

Multi-Language

Mehrsprachigkeit ist verfügbar, aber optional. Um sie zu aktivieren, sind zwei Schritte nötig.

1. Next.js für Mehrsprachigkeit konfigurieren:

const config = withMarkdownWebBook({
  // Enable i18n
  i18n: {
    locales: ['en', 'de'],
    defaultLocale: 'de'
  },
})

2. Projektstruktur mit sprachspezifischen Inhalten aufbauen:

your-content-directory/
├── en/
│   ├── index.mdx
│   ├── about.mdx
│   └── ...
├── de/
│   ├── index.mdx
│   ├── about.mdx
│   └── ...
└── ...

So stellst du sicher, dass Inhalte sauber pro Sprache getrennt sind und korrekt ausgeliefert werden.

6) editPage konfigurieren

Mit editPage aktivierst du den Link „Seite bearbeiten“ und legst fest, auf welches Repository der Link zeigt.

editPage: {
  enabled: true,
  description: 'Seite bearbeiten',
  repoBaseUrl: 'https://gitlab.com/deine-org/dein-projekt',
  icon: 'gitlab'
}

Parameter:

  • enabled (boolean, required): Aktiviert oder deaktiviert den Edit-Link.
  • description (string, optional): Text des Edit-Links.
  • repoBaseUrl (string, required): Basis-URL deines Repositories.
  • icon (optional): Eines von auto, edit, github, opencode, gitlab, none.

7) Custom Theme Components importieren und nutzen

Die Bibliothek exportiert u. a.:

  • CallToAction
  • Faqs
  • Features
  • Feedback
  • ReviewCarousel
  • LogoCloud

Beispiel:

import {
  CallToAction,
  Faqs,
  Features,
  Feedback,
  ReviewCarousel,
  LogoCloud,
} from '@document-writing-tools/kernux-nextra-theme'

Beispiele und Hinweise findest du im Bereich Komponenten.