Dokumentace v GitBooku s Git Sync: obsah v repozitáři i v editoru

Dokumentace, která žije mimo kód, rychle zastará. GitBook nabízí funkci Git Sync: obsah dokumentace se obousměrně synchronizuje s Markdown soubory v GitHub (nebo GitLab) repozitáři. Vývojáři píší v editoru a přes pull requesty, netechnici v přehledném webovém editoru GitBooku – a obě strany vidí totéž.

Jak Git Sync funguje

• Každý space (jedna dokumentace) v GitBooku lze propojit s jedním repozitářem a větví.
• Změna v GitBooku (sloučený change request) se zapíše jako commit do repozitáře.
• Commit do propojené větve se promítne do GitBooku.
• Obsah se ukládá jako běžné Markdown soubory, takže dokumentaci máte i v Gitu se vší historií.

Rozhraní GitBooku se průběžně mění, názvy tlačítek se proto mohou mírně lišit – princip zůstává stejný.

Nastavení krok za krokem

1. V GitBooku otevřete space a v jeho nastavení zvolte Configure / Git Sync.
2. Vyberte GitHub Sync a autorizujte účet.
3. Nainstalujte GitBook GitHub App a povolte jí přístup jen ke konkrétnímu repozitáři (ne ke všem).
4. Zvolte repozitář a větev, např. main nebo samostatnou docs.
5. Zvolte směr první synchronizace: - GitBook → GitHub: obsah ze space se zapíše do repozitáře (když začínáte v GitBooku), - GitHub → GitBook: obsah z repozitáře se načte do space (když už máte Markdown v repu).

Na směru první synchronizace záleží: obsah na cílové straně bude přepsán. Pokud si nejste jistí, vyzkoušejte to nejdřív na prázdném testovacím space nebo nové větvi.

Struktura souborů v repozitáři

docs/
├── .gitbook.yaml          # volitelné, viz níže
├── README.md              # úvodní stránka
├── SUMMARY.md             # obsah (navigace)
├── zaciname/
│   ├── README.md
│   └── instalace.md
└── .gitbook/
    └── assets/            # obrázky nahrané v GitBooku

SUMMARY.md určuje pořadí a hierarchii stránek v navigaci:

# Table of contents

* [Úvod](README.md)

## Začínáme

* [Začínáme](zaciname/README.md)
  * [Instalace](zaciname/instalace.md)

## Reference

* [API](reference/api.md)

Nadpisy druhé úrovně v SUMMARY.md vytvoří skupiny v postranním menu. Pokud soubor chybí, GitBook ho vygeneruje ze struktury složek.

.gitbook.yaml: dokumentace v podsložce

Ve výchozím stavu GitBook čte kořen repozitáře. Pokud máte dokumentaci vedle kódu ve složce docs/ (typické pro monorepo), dejte do kořene repozitáře soubor .gitbook.yaml:

root: ./docs/

structure:
  readme: README.md
  summary: SUMMARY.md

redirects:
  stara-instalace: zaciname/instalace.md

• root – složka s dokumentací,
• structure – názvy úvodní stránky a obsahu (relativně k root),
• redirects – přesměrování starých URL po přejmenování stránek.

V monorepu lze mít více spaces propojených s jedním repozitářem, každý s jinou složkou (root). V nastavení Git Sync pak určíte, kterou cestu má space používat.

Pracovní postup pro vývojáře

Dokumentace se upravuje stejně jako kód:

git switch -c docs/popis-webhooku
# úprava docs/reference/webhooky.md + přidání do SUMMARY.md
git commit -am "docs: popsat webhooky pro objednávky"
git push -u origin docs/popis-webhooku
gh pr create --fill

Po sloučení PR do synchronizované větve se změna objeví v GitBooku. Výhoda: změna dokumentace může být ve stejném PR jako změna kódu, kterou popisuje, a projde stejným code review.

Pracovní postup pro netechnické kolegy

V GitBooku vytvoří change request (obdoba větve), upraví text v editoru a po schválení ho sloučí. GitBook to zapíše jako commit do repozitáře. Vývojáři pak udělají git pull a mají aktuální obsah.

Na co si dát pozor

• Souběžné úpravy stejné stránky v GitBooku a v Gitu mohou vést ke konfliktu synchronizace. Domluvte se, kde se která část primárně edituje.
• Speciální bloky GitBooku (hints, tabs, embedy) se v Markdownu ukládají jako značky typu {% hint style="info" %}. Při ruční editaci je zachovejte, jinak se rozbijí.
• Obrázky nahrané v GitBooku končí ve složce .gitbook/assets/. Při úpravách v Gitu používejte relativní cesty.
• Ochrana větve: pokud má cílová větev povinné PR a schválení, GitBook do ní nemusí mít možnost přímo zapisovat. Zvažte samostatnou větev pro dokumentaci nebo upravte pravidla.
• CI: commity od GitBooku spustí i vaše workflow. Pomocí paths-ignore: ['docs/**'] v GitHub Actions zabráníte zbytečným buildům aplikace.

on:
  push:
    branches: [main]
    paths-ignore:
      - "docs/**"

Alternativy

Pokud nepotřebujete webový editor pro netechnické kolegy, stejného výsledku „dokumentace v Gitu“ dosáhnete statickými generátory jako MkDocs (s tématem Material), Docusaurus nebo VitePress, nasazenými přes GitHub Pages. GitBook vyniká hlavně v kombinaci vývojářů a ne-vývojářů nad jedním obsahem.