Docusaurus - zielony przyjaciel tech writera

Generator stron statycznych stworzony z myślą o dokumentacji. Czy się faktycznie nadaje? Oto nasze wrażenia.

Co to jest Docusaurus?

Docusaurus to Static Site Generator, czyli aplikacja do generowania stron statycznych. Przedstawicielem tej grupy jest na przykład DITA OT, ale jest ich znacznie więcej. Podobnie jak DITA OT, Docusaurus został stworzony do dokumentacji, ale nie ma on nic wspólnego z ditą. W Docusaurusie piszemy w formacie Markdown, a konkretnie MDX.

W dużym skrócie, projekt strony z Docusaurusem ma folder "docs" w którym piszemy swoje strony (topiki, artykuły) i plik, który pozwala nam zarządzać nawigacją.

Jeżeli korzystacie z narzędzi wokół programowania front-end, to na pewno widzieliście już Docusaurusa, na przykład na stronie Yarn albo Testing Library. Jeżeli nie, to może zauważyliście, że (w momencie publikacji tego artykułu) Docusaurus zasila strony MeetContent i stronę, którą aktualnie czytasz.

Dlaczego do dokumentacji?

Docusaurus od początku był stworzony z myślą o dokumentacji do projektów open source dla firmy Meta (ówcześnie Facebook Open Source). Joel Marcey, ich developer advocate, napisał w 2017, że Docusaurus powstał po to, aby:

1. Skupić się na pisaniu dobrej dokumentacji zamiast martwić się o infrastrukturę strony.
2. Dać stronom dokumentacyjnym najważniejsze funkcjonalności, czyli wersjonowanie, wyszukiwanie i blogowanie.
3. Dzielić się ze społecznością open source najnowszymi funkcjonalnościami i bug fixami w przystepny sposób. Osiągnęli to publikując Docusaurusa jako biblioteki NPMowe.
4. Żeby stronki o ich projektach open source miały wspólny wygląd i funkcjonalność.

Ta ostatni cecha przysłużyła się szerszej społeczności i stała się swego rodzaju standardem w pewnych kręgach.

Docusaurus ma typowe cechy strony z dokumentacją:

• Strona domowa z linkami do najważniejszych miejsc.
• Podstronki z dokumentacją i nawigacją po lewej, która pozwala się po nich swobodnie poruszać.
• Pole wyszukiwania w prawym górnym rogu.
• Sekcja "blog".
• Strona z wersjami i linkami do release note'ów.
• Numer wersji w górnym pasku strony i możliwość przełączania się między wersjami.
• Możliwość przełączania się między językami.

Dodatkowo, na stronach z dokumentacją można używać wszelkich dobrodziejstw Markdowna. Oprócz typowych list, tabel, linków i obrazków, możesz znaleźć takie rzeczy jak bloki kodu, wyróżnione notki, czy sekcje zwijane. Zobacz nasze przykłady poniżej.

Bloki kodu (code blocks) z pokolorowanymi literkami i przyciskiem do kopiowania. Można je też wzbogacić o działający podgląd, jeżeli próbka kodu jest na przykład napisana w Reakcie. Co więcej, można pozwolić użytkownikowi edytować ten podgląd, tak jak poniżej.

Edytor live

function FruitMachine(props) {
  const [fruit, setFruit] = useState([]);

  // tutaj wpisz swoje imię:
  const name = 'Balthazar';

  const fruitList = [
    {
      fruitEmoji: '🍌',
      label: 'Add banana',
    },
    {
      fruitEmoji: '🍎',
      label: 'Add apple',
    },
    {
      fruitEmoji: '🍑',
      label: 'Add peach',
    },
    {
      fruitEmoji: '🥦',
      label: 'Add broccoli (technically, a vegetable)',
    },
  ];

  function addFruit(value) {
    setFruit((existingFruit) => [...existingFruit, value]);
  }

  return (
    <div
      style={{
        margin: '1rem 0',
      }}
    >
      <div style={{ display: 'flex', flexDirection: 'column', gap: '6px' }}>
        {fruitList.map(({ fruitEmoji, label }) => (
          <button
            key={label}
            role="button"
            onClick={() => addFruit(fruitEmoji)}
            className="button button--primary"
          >
            {label}
          </button>
        ))}
      </div>
      <div className="card padding--lg" style={{ flex: 1 }}>
        <h3>
          Hello, {name}! You currently have {fruit.length} fruit.
        </h3>
        <div>You have: {fruit.join(' ')}</div>
      </div>
    </div>
  );
}

Rezultat

Loading...

Wyróżnione notki typu "ważne", "uwaga", "niebezpieczeństwo", itp. (tzw. admonitions).

Uwaga: NUDA!

Osiągnięcie zbyt wysokiego poziomu umiejętności może sprawić, że większość zadań będzie Cię nudzić. Dlatego rób rzeczy byle jak.

Taby do wyświetlania różnych wersji tej samej rzeczy.

Windows

format C:

MacOS

mkfs.(anything)

Linux

rm -rf /

Sekcje zwijane (tzw. "zwijaki").

Rozwiń

Tutaj więcej szczegółów

Ciekawe co jest dalej? 🤔

Wersjonowanie

Docusaurus pozwala na stworzenie strony, która zawiera w sobie wiele wersji. To dobre podejście dla małych, zamkniętych projektów, które pozwala użytkownikowi na wgląd w dowolną wersję w zależności od potrzeb. Mechanizm wersjonowania jest dosyć prosty w obsłudze i jest w pełni opcjonalny. Cała strona może być skonstruowana tak, że reprezentuje tylko jedną najnowszą wersję.

Wyszukiwanie

Docusaurus pozwala na prostą integrację z serwisem Algolia. To dobra opcja, jeżeli nasza strona jest powszechnie dostępna w Internecie, bo Algolia wymaga otwartego dostępu, żeby zindeksować stronę. Jeżeli to nie pasuje do naszej sytuacji, możemy skorzystać z innej z dostępnych opcji, w tym dołączyć swój własny mechanizm wyszukiwania.

Reuse

Docusaurus posiada opcję wielokrotnego użycia tego samego fragmentu za pomocą importów w pliku Markdown. Co więcej, takie fragmenty mogą mieć parametry, dzięki czemu stają się jeszcze bardziej uniwersalne. Na przykład:

_fruit.mdx

Mój ulubiony owoc to {props.fruit}!

Używamy go w taki sposób:

import Fruit from './\_fruit.mdx';

<Fruit fruit="🍌" />

<Fruit fruit="🥦" />

Mój ulubiony owoc to 🍌!

Mój ulubiony owoc to 🥦!

Tłumaczenie

Docusaurus ma wbudowany kompletny mechanizm, który pozwala przetłumaczyć większość stron w większości przypadków. Jedyny wyjątek stanowi skomplikowane użycie plików MDX, które jeszcze nie jest do końca proste do przetłumaczenia. Ale są sposoby, żeby to obejść.

Podstawą mechanizmu tłumaczenia są dwa aspekty:

• Pliki MDX są tłumaczone jak pliki Markdown. Większość agencji tłumaczeniowych i narzędzi do tłumaczeń powinna sobie z tym poradzić.
• Tłumaczenie customowych stron JSX/TSX i innego kodu możemy osiągnąć używając wbudowanych komend, które ekstrahują tekst do plików JSON.

Blogowanie

Jeżeli chcecie publikować nowości o Waszym projekcie, Docusaurus proponuje zrobić to przez moduł do blogowania. Każdy post na blogu jest plikiem MDX i zachowuje się bardzo podobnie do strony z docsami, ale dodatkowo ma datę. Posiada też tagi, które pozwalają wyświetlić listę podobnych wpisów.

JSX, React i Node.js

Format MDX używany w Docusaurusie pozwala na używanie komponentów JSX lub TSX (TypeScript), czyli elementów strony napisanych w Reakcie. Jeżeli potrafisz programować, lub znasz kogoś kto potrafi, to otwiera całą masę możliwości:

• Konfigurowalne formularze
• Tabele, listy, lub sekcje, których treść pochodzi ze źródła danych
• Strony generowanie w czasie budowania, na przykład zawierające listy błędów lub parametrów
• Interaktywne próbki kodu z plików, które mogą być testowane pod kątem poprawności
• Pięknie wystylizowanie karty, galerie, karuzele i tym podobne.

Docusaurus jest budowany za pomocą Node.js. To oznacza, że w momencie budowania mamy pełną władzę nad tym skąd pochodzi treść co daje nam sporo opcji automatyzacji. Możemy wszystko napisać ręcznie, ale możemy też niektóre lub wszystkie strony wygenerować. Na przykład możemy pobrać dane z bazy i wygenerować z nich tabele, albo zebrać wpisy na bloga z CMSa, lub release notes z Jiry. Dla majsterkowicza z odrobiną zapału wszystko jest możliwe.

Cena

W momencie publikacji artykułu, Docusaurus jest darmowy i można go wykorzystywać dowolnie, ale zapoznajcie się z warunkami licencji zanim skoczycie na głęboką wodę. Ten wpis na blogu nie stanowi porady prawnej, oferty handlowej, ani nie może byc użyty jako kupon zniżkowy w sklepie z rowerami.

Hostowanie

Magia stron statycznych polega na tym, że można je hostować praktycznie wszędzie! Co to oznacza? Poradzi sobie z nimi dowolny serwer o architekturze podobnej do Apache Web Server, dowolny CDN, czy serwis taki jak Amazon S3. Docusaurus generuje pliki HTML, CSS i Javascript czyli absolutny standard.

Dobrą opcją na hostowanie Docusaurusa są GitHub Pages, ale możecie skorzystać z bardzo wielu innych, o czym przeczytacie na stronie "Deployment".

Jak zacząć

Wszystko jest opisane tutaj. Ale z grubsza wygląda to tak:

1. Zainstaluj Node.js (np. przez NVM).
2. Zainstaluj Docusaurusa, żeby stworzyć lokalny folder projektu.
3. Napisz docsy w Markdownie.
4. Wypchnij zmiany do systemu kontroli wersji.
5. Opublikuj.
6. Czerp korzyści i zyskaj niezależność finansową.

A Wy korzystaliście już z Docusaurusa? Jeśli tak, dajcie nam znać w komentarzach co sądzicie o tym narzędziu.