feat: добавление docusaurus

Reviewed-on: #1
Co-authored-by: Arswarog <arswarog@yandex.ru>
Co-committed-by: Arswarog <arswarog@yandex.ru>

.gitignore

@@ -0,0 +1 @@
+.idea

action.yml

@@ -5,6 +5,9 @@ inputs:
   docs-path:
     description: 'Path to docs directory in calling repo'
     default: 'docs'
+  on-broken-links:
+    description: 'Behavior on broken links: throw, warn, or ignore'
+    default: 'throw'
 
 runs:
   using: 'composite'
@@ -17,13 +20,15 @@ runs:
         ORG="${{ github.repository_owner }}"
 
         if [[ "$REF" == "main" || "$REF" == "master" ]]; then
-          URL="http://${REPO}.${ORG}.docs.jt4d.ru.net"
+          URL="http://${REPO}.${ORG}.jt4d-wiki.ru.net"
+          S3_PATH="${ORG}.${REPO}"
         else
-          URL="http://${REF}.${REPO}.${ORG}.docs.jt4d.ru.net"
+          URL="http://${REF}.${REPO}.${ORG}.jt4d-wiki.ru.net"
+          S3_PATH="${ORG}.${REPO}.${REF}"
         fi
 
         echo "TARGET_URL=$URL" >> $GITHUB_ENV
-        echo "S3_PATH=${ORG}.${REPO}.${REF}" >> $GITHUB_ENV
+        echo "S3_PATH=$S3_PATH" >> $GITHUB_ENV
 
     - name: Set docs status pending
       shell: bash
@@ -42,20 +47,27 @@ runs:
     - name: Copy docs into Docusaurus
       shell: bash
       run: |
-        DOCUSAURUS_DIR="${{ github.action_path }}docusaurus"
+        DOCUSAURUS_DIR="${{ github.action_path }}/docusaurus"
         rm -rf "${DOCUSAURUS_DIR}/docs"
         cp -r "${{ inputs.docs-path }}" "${DOCUSAURUS_DIR}/docs"
         cp "${{ github.workspace }}/.docuservix.yml" "${DOCUSAURUS_DIR}"
-        
+
+    - name: Prepare docs
+      shell: bash
+      working-directory: ${{ github.action_path }}/docusaurus
+      run: node scripts/prepare-docs.mjs
 
     - name: Install Docusaurus dependencies
       shell: bash
-      working-directory: ${{ github.action_path }}docusaurus
+      working-directory: ${{ github.action_path }}/docusaurus
       run: yarn install --frozen-lockfile
 
     - name: Build docs
       shell: bash
-      working-directory: ${{ github.action_path }}docusaurus
+      working-directory: ${{ github.action_path }}/docusaurus
+      env:
+        DOCUSERVIX_ON_BROKEN_LINKS: ${{ inputs.on-broken-links }}
+        DOCUSERVIX_URL: ${{ env.TARGET_URL }}
       run: yarn docusaurus build --out-dir ${{ github.workspace }}/generated-docs
 
     - name: Upload to S3
@@ -65,7 +77,7 @@ runs:
         AWS_SECRET_ACCESS_KEY: ${{ vars.DOCUSERVIX_S3_SECRET }}
       run: |
         aws s3 sync generated-docs/ \
-          s3://${{ vars.DOCUSERVIX_S3_BUCKET }}/docs.${{ env.S3_PATH }}\
+          s3://${{ vars.DOCUSERVIX_S3_BUCKET }}/${{ env.S3_PATH }}\
           --endpoint-url ${{ vars.DOCUSERVIX_S3_URL }} \
           --acl public-read \
           --delete

docusaurus/.docuservix.yml

@@ -0,0 +1,4 @@
+title: "Title example"
+project:
+  org: "example"
+  repo: "example"

docusaurus/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docusaurus/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```bash
+yarn
+```
+
+## Local Development
+
+```bash
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```bash
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

docusaurus/docs/index.md

@@ -0,0 +1,3 @@
+# Добро пожаловать в Docuservix!
+
+Вам надо настроить публикацию документации по инструкции в https://git.jt4d.ru/jt4d/docuservix

docusaurus/docusaurus.config.ts

@@ -0,0 +1,133 @@
+import fs from 'fs';
+import yaml from 'js-yaml';
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+import type {NavbarItem} from '@docusaurus/theme-common'
+
+interface DocsConfig {
+    title: string;
+    project: { org: string; repo: string };
+    dirs?: { docs?: string; blog?: string };
+}
+
+const docsConfig = yaml.load(fs.readFileSync('./.docuservix.yml', 'utf8')) as DocsConfig;
+
+const {
+    title,
+} = docsConfig
+
+const url = process.env.DOCUSERVIX_URL;
+
+const {
+    org,
+    repo
+} = docsConfig.project
+
+const {
+    docs: docsDir = 'docs',
+    blog: blogDir
+} = docsConfig.dirs || {}
+
+const giteaUrl = 'https://git.jt4d.ru';
+const onBrokenLinks = (process.env.DOCUSERVIX_ON_BROKEN_LINKS as Config['onBrokenLinks']) || 'throw';
+
+const config: Config = {
+    title,
+    favicon: 'img/favicon.ico',
+
+    markdown: {
+        mermaid: true,
+    },
+    themes: ['@docusaurus/theme-mermaid'],
+
+    // Future flags, see https://docusaurus.io/docs/api/docusaurus-config#future
+    future: {
+        v4: true, // Improve compatibility with the upcoming Docusaurus v4
+    },
+
+    // Set the production url of your site here
+    url,
+    // Set the /<baseUrl>/ pathname under which your site is served
+    // For GitHub pages deployment, it is often '/<projectName>/'
+    baseUrl: '/',
+
+    // GitHub pages deployment config.
+    // If you aren't using GitHub pages, you don't need these.
+    organizationName: org,
+    projectName: repo,
+
+    onBrokenLinks,
+
+    // Even if you don't use internationalization, you can use this field to set
+    // useful metadata like html lang. For example, if your site is Chinese, you
+    // may want to replace "en" with "zh-Hans".
+    i18n: {
+        defaultLocale: 'ru',
+        locales: ['ru'],
+    },
+
+    presets: [
+        [
+            'classic',
+            {
+                blog: {
+                    showReadingTime: true,
+                    feedOptions: {
+                        type: ['rss', 'atom'],
+                        xslt: true,
+                    },
+                    // Useful options to enforce blogging best practices
+                    onInlineTags: 'warn',
+                    onInlineAuthors: 'warn',
+                    onUntruncatedBlogPosts: 'warn',
+                },
+                theme: {
+                    customCss: './src/css/custom.css',
+                },
+            } satisfies Preset.Options,
+        ],
+    ],
+
+    themeConfig: {
+        // Replace with your project's social card
+        image: 'img/docusaurus-social-card.jpg',
+        colorMode: {
+            respectPrefersColorScheme: true,
+        },
+        navbar: {
+            title: title,
+            logo: {
+                alt: 'Logo',
+                src: 'img/logo.svg',
+            },
+            items: [
+                {
+                    to: '/docs',
+                    label: 'Документация',
+                    position: 'left',
+                },
+                blogDir ? {
+                    to: '/blog',
+                    label: 'Блог',
+                    position: 'left'
+                } : undefined,
+                {
+                    href: `${giteaUrl}/${org}/${repo}`,
+                    label: 'Gitea',
+                    position: 'right',
+                },
+            ].filter((item): item is NavbarItem => !!item),
+        },
+        footer: {
+            style: 'dark',
+            copyright: `Проект хостится на JT4D.ru, документация собрана с использованием Docuservix и Docusaurus.`,
+        },
+        prism: {
+            theme: prismThemes.github,
+            darkTheme: prismThemes.dracula,
+        },
+    } satisfies Preset.ThemeConfig,
+};
+
+export default config;

docusaurus/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "docusaurus",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.10.1",
+    "@docusaurus/faster": "3.10.1",
+    "@docusaurus/preset-classic": "3.10.1",
+    "@docusaurus/theme-mermaid": "3.10.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "js-yaml": "^4.2.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.10.1",
+    "@docusaurus/tsconfig": "3.10.1",
+    "@docusaurus/types": "3.10.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/react": "^19.0.0",
+    "typescript": "~6.0.2"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}

docusaurus/scripts/prepare-docs.mjs

@@ -0,0 +1,31 @@
+import fs from 'fs';
+import path from 'path';
+
+const docsDir = path.resolve(import.meta.dirname, '..', process.argv[2] || 'docs');
+
+pinIndexToTop();
+
+/**
+ * Гарантирует наличие sidebar_position: 0 в front matter файла index.md
+ */
+function pinIndexToTop() {
+  const indexPath = path.join(docsDir, 'index.md');
+  if (!fs.existsSync(indexPath)) return;
+
+  let content = fs.readFileSync(indexPath, 'utf8');
+
+  if (content.startsWith('---\n')) {
+    const endIdx = content.indexOf('\n---\n', 4);
+    if (endIdx === -1) return;
+
+    const frontMatter = content.slice(4, endIdx);
+    if (/^sidebar_position\s*:/m.test(frontMatter)) return;
+
+    content = '---\nsidebar_position: 0\n' + frontMatter + '\n---\n' + content.slice(endIdx + 5);
+  } else {
+    content = '---\nsidebar_position: 0\n---\n' + content;
+  }
+
+  fs.writeFileSync(indexPath, content);
+  console.log('prepare-docs: pinned index.md to sidebar top');
+}

docusaurus/src/css/custom.css

@@ -0,0 +1,30 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

docusaurus/src/pages/index.module.css

@@ -0,0 +1,23 @@
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+}
+
+@media screen and (max-width: 996px) {
+  .heroBanner {
+    padding: 2rem;
+  }
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}

docusaurus/src/pages/index.tsx

@@ -0,0 +1,40 @@
+import type {ReactNode} from 'react';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import Layout from '@theme/Layout';
+import Heading from '@theme/Heading';
+
+import styles from './index.module.css';
+
+function HomepageHeader() {
+  const {siteConfig} = useDocusaurusContext();
+  return (
+    <header className={clsx('hero hero--primary', styles.heroBanner)}>
+      <div className="container">
+        <Heading as="h1" className="hero__title">
+          {siteConfig.title}
+        </Heading>
+        <p className="hero__subtitle">{siteConfig.tagline}</p>
+        <div className={styles.buttons}>
+          <Link
+            className="button button--secondary button--lg"
+            to="/docs">
+            Документация
+          </Link>
+        </div>
+      </div>
+    </header>
+  );
+}
+
+export default function Home(): ReactNode {
+  const {siteConfig} = useDocusaurusContext();
+  return (
+    <Layout
+      title={`Hello from ${siteConfig.title}`}
+      description="Description will go into a meta tag in <head />">
+      <HomepageHeader />
+    </Layout>
+  );
+}

docusaurus/src/pages/markdown-page.mdx

@@ -0,0 +1,7 @@
+---
+title: Markdown page example
+---
+
+# Markdown page example
+
+You don't need React to write simple standalone pages.

docusaurus/tsconfig.json

@@ -0,0 +1,12 @@
+// This file is not used by "docusaurus start/build" commands.
+// It is here to improve your IDE experience (type-checking, autocompletion...),
+// and can also run the package.json "typecheck" script manually.
+{
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "ignoreDeprecations": "6.0",
+    "strict": true
+  },
+  "exclude": [".docusaurus", "build"]
+}