feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,128 @@
+# Docusaurus Config Template — Modern Dark Theme
+
+Full `docusaurus.config.ts` for a modern dark-first docs site with:
+- draw.io plugin (`docusaurus-plugin-drawio`)
+- Mermaid C4 diagrams (`@docusaurus/theme-mermaid`)
+- Dark mode default
+- Prism oneDark theme
+- Announcement bar
+- Sidebar TOC config
+
+```ts
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'My Project',
+  tagline: 'Documentation tagline',
+  favicon: 'img/favicon.ico',
+
+  url: 'https://docs.example.com',
+  baseUrl: '/',
+
+  organizationName: 'org-name',
+  projectName: 'documentation',
+
+  onBrokenLinks: 'throw',
+  markdown: {
+    hooks: {
+      onBrokenMarkdownLinks: 'warn',
+    },
+    mermaid: true,
+  },
+
+  i18n: { defaultLocale: 'en', locales: ['en'] },
+
+  themes: ['@docusaurus/theme-mermaid'],
+
+  plugins: ['docusaurus-plugin-drawio'],
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          editUrl: 'https://gitea.lego-cloud.eu/ORG/REPO/src/branch/main/',
+          showLastUpdateTime: true,
+          showLastUpdateAuthor: true,
+        },
+        blog: {
+          showReadingTime: true,
+          blogTitle: 'Changelog',
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'dark',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+
+    announcementBar: {
+      id: 'wip',
+      content: '🚧 Under active development.',
+      backgroundColor: '#1a1a2e',
+      textColor: '#818cf8',
+      isCloseable: true,
+    },
+
+    navbar: {
+      title: 'My Project',
+      hideOnScroll: true,
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'docsSidebar',
+          position: 'left',
+          label: 'Docs',
+        },
+        {
+          href: 'https://gitea.lego-cloud.eu/ORG',
+          position: 'right',
+          label: 'Gitea ↗',
+        },
+      ],
+    },
+
+    footer: {
+      style: 'dark',
+      copyright: `© ${new Date().getFullYear()} My Project · Built by Jarvis`,
+    },
+
+    prism: {
+      theme: prismThemes.oneDark,
+      darkTheme: prismThemes.oneDark,
+      additionalLanguages: ['bash', 'python', 'sql', 'yaml', 'json', 'typescript', 'docker'],
+    },
+
+    mermaid: {
+      theme: { light: 'neutral', dark: 'dark' },
+    },
+
+    tableOfContents: {
+      minHeadingLevel: 2,
+      maxHeadingLevel: 4,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;
+```
+
+## Required packages
+```bash
+npx pnpm add @docusaurus/theme-mermaid docusaurus-plugin-drawio raw-loader
+```
+
+## Pitfalls
+- `onBrokenMarkdownLinks` moved to `markdown.hooks.onBrokenMarkdownLinks` in Docusaurus v3 — using `siteConfig.onBrokenMarkdownLinks` triggers a deprecation warning
+- Remove blog from navbar if you have no blog posts — broken link on build
+- `to: 'https://...'` does NOT work for external links in navbar; use `href:` instead