Przejdź do głównej zawartości

Docusaurus

Docusaurus to framework do tworzenia dokumentacji technicznej w formie nowoczesnych stron internetowych. Bazuje na React i wspiera Markdown.

🔧 Instalacja​

Wymagania​

  • Node.js (zalecana wersja LTS)
  • npm lub yarn
sudo apt update
sudo apt install nodejs npm

Tworzenie nowego projektu​

npx create-docusaurus@latest my-website classic
cd my-website
npm install
npm run start

Wybieram wersję TypeScript

Otworzy się lokalna strona pod adresem http://localhost:3000.

🗂️ Struktura projektu​

my-website/
├── blog/               # posty blogowe (opcjonalnie)
├── docs/               # pliki dokumentacji (Markdown)
├── src/pages/          # niestandardowe strony React
├── static/             # statyczne pliki (obrazy, PDF itp.)
├── docusaurus.config.js# konfiguracja witryny
└── sidebars.js         # definicja nawigacji dokumentacji

📄 Dokumentacja w Markdown​

Każdy plik .md w katalogu docs/ to osobna strona. Przykład:

---
id: wprowadzenie
title: Wprowadzenie
---

# Witaj w dokumentacji

To jest treść Twojej dokumentacji.

📚 Sidebar (menu nawigacyjne)​

sidebars.js definiuje strukturę:

module.exports = {
  tutorialSidebar: [
    'wprowadzenie',
    {
      type: 'category',
      label: 'Sekcja',
      items: ['plik1', 'plik2']
    },
  ],
};

🎨 Personalizacja​

Docusaurus umożliwia edycję:

  • logotypu, nazw i kolorów w docusaurus.config.js
  • stylów CSS w src/css/custom.css
  • układów i komponentów React

✍️ Blog (opcjonalny)​

W katalogu blog/ umieszczasz pliki .md z frontmatter:

---
title: Pierwszy wpis
author: Jan Kowalski
date: 2025-04-21
---

To jest wpis blogowy.

🚀 Publikacja​

Możesz zbudować statyczną stronę:

npm run build

Pliki znajdziesz w katalogu build/. Możesz je opublikować na GitHub Pages, Netlify, Vercel itp.

Przykład dla GitHub Pages:

git init
npm run build
git add build -f
git commit -m "deploy"
git subtree push --prefix build origin gh-pages

🧩 Pluginy i rozszerzenia​

Docusaurus wspiera pluginy, np.:

  • wyszukiwarka lokalna (@cmfcmf/docusaurus-search-local)
  • Google Analytics
  • plugin do OpenAPI

Instalacja:

npm install @cmfcmf/docusaurus-search-local

Dodaj do docusaurus.config.js:

plugins: [
  [
    require.resolve('@cmfcmf/docusaurus-search-local'),
    {
      indexDocs: true,
      indexPages: true,
      language: ['pl'],
    },
  ],
],

🔚 Podsumowanie​

Docusaurus to potężne narzędzie do tworzenia eleganckiej, interaktywnej dokumentacji. Dzięki Markdown i React pozwala szybko rozwijać projekt i łatwo go personalizować.

Więcej: https://docusaurus.io