Opensophy Hub: SSG/SPA dla dokumentacji Markdown

Opensophy Hub: statyczna platforma SSG/SPA dla zaawansowanej dokumentacji Markdown

Opensophy Hub to hybrydowa platforma oparta na SSG i SPA, przeznaczona do publikowania dokumentacji technicznej, artykułów i instrukcji obsługi. Rozwiązuje problem przechowywania treści z rozszerzonymi możliwościami Markdown bez konieczności używania MDX czy dodatkowych wtyczek. Struktura projektu jest generowana bezpośrednio ze struktury plików w katalogu Docs/, gdzie foldery określają nawigację: pasek boczny, breadcrumbs i URL są tworzone automatycznie.

Przykład struktury:

Docs/
├── welcome.md
├── [N][brain]Withtati{article}/
│   ├── [C][folder-code]Razrabotka{development}/
│   │   └── [A][layers]Vybor steka{webrendering}.md
│   └── [C][signal]Instrumenty{tools}/
│       └── [A][container]Obzor Dokploy{dokploy}.md

Trzy poziomy hierarchii — sekcje ([N]), kategorie ([C]), artykuły ([A]) — zapewniają slugi, ikony i nazwy bez ręcznej konfiguracji routingu. Upraszcza to utrzymanie i skalowanie treści dla middle/senior developerów.

Rozszerzony Markdown bez zależności

Hub wprowadza bogate bloki bezpośrednio do standardowych plików .md: alerty, karty, kolumny, steppery, diagramy, formuły KaTeX i wykresy z tabel. Zamiast znaczników HTML z klasami stosowane są proste konstrukcje składniowe.

Przykład alertu w HTML:

<div class="alert alert-warning" role="alert">
  <strong>Ostrożnie!</strong> Usunięte za pomocą <code>rm</code> pliki nie trafiają do kosza.
</div>

W Hub:

:::caution
Usunięte za pomocą `rm` pliki nie trafiają do kosza.
:::

Instrukcja krok po kroku (stepper):

:::steps
:::step[status=done] Instalacja
`npm install`
:::
:::step[status=active] Konfiguracja
Wypełnij `.env`.
:::
:::step[status=pending] Uruchomienie
`npm run dev`
:::
:::

Takie bloki są renderowane natywnie, bez zewnętrznych bibliotek, co zmniejsza złożoność budowania i poprawia wydajność trybu SPA.

Interaktywne tabele i UI-playgrounds

Standardowe tabele Markdown są przekształcane w interaktywne komponenty z filtrami po kolumnach (multi-select), wyszukiwaniem z podświetleniem, ukrywanie kolumn, fullscreen, drag-to-scroll i eksportem do Markdown/Excel.

Dodatkowo obsługuje osadzanie live-komponentów biblioteki UI jedną linią:

[uic:blur-text]

Użytkownik może dynamicznie zmieniać parametry — skalę, kolor, animację, prędkość — i obserwować wynik w czasie rzeczywistym. Jest to przydatne do demonstracji komponentów w dokumentacji bez osobnego playground.

Panel CMS do edycji

Wbudowany panel zarządzania treścią pozwala edytować Markdown z podglądem live. Tworzenie stron, kategorii i sekcji odbywa się w interfejsie bez restartów npm run dev czy skryptów. Obsługa wszystkich formatów bloków zapewnia workflow zbliżony do pełnoprawnej CMS, ale oparty na statycznej generacji.

Zalety dla programistów:

• Automatyczna nawigacja ze struktury plików.
• Rozszerzony Markdown bez wtyczek i MDX.
• Interaktywne tabele z filtrami i eksportem.
• Live-playgrounds dla komponentów UI.
• Edytor przypominający CMS z podglądem.

Co ważne

• Struktura plików jako nawigacja: Pełna automatyzacja routingu, breadcrumbs i paska bocznego z prefiksów [N], [C], [A].
• Natywne bloki Markdown: Alerty, steppery, kolumny, KaTeX, wykresy — bez zależności.
• Interaktywność tabel: Filtry, wyszukiwanie, fullscreen, eksport do MD/Excel.
• UI-playgrounds: Jedna linia dla live-demo komponentów z parametrami.
• Interfejs CMS: Edycja z podglądem bez budowania.

— Editorial Team