Настройка и кастомизация темы Docusaurus

Настройка и кастомизация темы Docusaurus

Docusaurus предоставляет механизм swizzling — переопределение встроенных компонентов. Можно изменить любой элемент: навигацию, footer, карточки документов, цвета.

CSS-переменные для цветовой схемы

/* src/css/custom.css */
:root {
  --ifm-color-primary: #2563eb;
  --ifm-color-primary-dark: #1d4ed8;
  --ifm-color-primary-darker: #1e40af;
  --ifm-color-primary-darkest: #1e3a8a;
  --ifm-color-primary-light: #3b82f6;
  --ifm-color-primary-lighter: #60a5fa;
  --ifm-color-primary-lightest: #93c5fd;
  --ifm-code-font-size: 90%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 255, 0.1);
}

[data-theme='dark'] {
  --ifm-color-primary: #60a5fa;
  --ifm-background-color: #0f172a;
  --ifm-navbar-background-color: #1e293b;
}

Swizzle: кастомный Footer

npm run swizzle @docusaurus/theme-classic Footer -- --eject --typescript
# Создаёт src/theme/Footer/index.tsx

// src/theme/Footer/index.tsx
import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function Footer(): JSX.Element {
  const { siteConfig } = useDocusaurusContext();
  return (
    <footer className="footer">
      <div className="container">
        <div className="footer__links">
          <a href="https://github.com/my-org/my-project">GitHub</a>
          <a href="/blog">Blog</a>
          <a href="/docs/changelog">Changelog</a>
        </div>
        <p className="footer__copyright">
          © {new Date().getFullYear()} {siteConfig.title}
        </p>
      </div>
    </footer>
  );
}

Swizzle: кастомная homepage

# Wrap (безопаснее чем eject)
npm run swizzle @docusaurus/theme-classic DocCard -- --wrap

Кастомная главная страница

// src/pages/index.tsx
import React from 'react';
import Layout from '@theme/Layout';
import Link from '@docusaurus/Link';

export default function Home(): JSX.Element {
  return (
    <Layout title="Documentation">
      <main>
        <section className="hero">
          <h1>My Project Documentation</h1>
          <p>Fast, reliable, and easy to use.</p>
          <div>
            <Link className="button button--primary button--lg" to="/docs/intro">
              Get Started →
            </Link>
            <Link className="button button--secondary button--lg" to="/docs/api">
              API Reference
            </Link>
          </div>
        </section>
      </main>
    </Layout>
  );
}

Прагмы в Markdown

<!-- Скрыть страницу из sidebar, но оставить по URL -->
---
hide_table_of_contents: true
hide_title: false
pagination_prev: null
pagination_next: null
---

<!-- Подсветка строк в коде -->
```js
function hello() {
  // highlight-next-line
  console.log('highlighted');
  // highlight-start
  const x = 1;
  const y = 2;
  // highlight-end
}

Кастомизация темы с переопределением 3–5 компонентов и кастомной homepage — 2–4 дня.