Jak tvořit a upravovat nápovědu

Tato dokumentace vzniká jako obyčejné markdown soubory v git repozitáři platform-docs/docs-source a web z nich generuje Astro Starlight. Každá změna projde běžným git workflow (větev → merge request → merge) a než se dostane do zveřejněné dokumentace, je vidět v připravované dokumentaci (viz Připravovaná a zveřejněná dokumentace).

Kde obsah žije

src/content/docs/         ← čeština leží rovnou tady
├── index.mdx             ← úvodní stránka → /
├── prvni-kroky/
│   └── index.md          ← /prvni-kroky
└── pro-editory/
    └── tvorba-napovedy.mdx  ← tato stránka

Cesta souboru = URL stránky. Soubor navody/obrazky.md bude dostupný na /navody/obrazky.
Jazyky: čeština je výchozí jazyk a je v adresách bez předpony — /prvni-kroky, ne /cs/prvni-kroky. Přibude-li další jazyk, dostane vlastní adresář a vlastní předponu: src/content/docs/en/ → /en/…. Česká URL se tím nezmění (i18n průvodce).

Nová stránka (rychlý přehled)

Vytvořte .md soubor ve správné sekci, např. src/content/docs/navody/obrazky.md.

Na začátek patří frontmatter — title je povinný:

---
title: Práce s obrázky
description: Krátký popis pro vyhledávače a náhledy.
---

Text stránky v běžném markdownu…

Stránka se sama objeví v levé navigaci své sekce.

Podrobně: Authoring Content a Pages v oficiální dokumentaci. Pro zvýrazněné bloky, karty a číslované postupy viz Components — základ zvládnete i bez nich, obyčejný markdown stačí.

Nová sekce (rychlý přehled)

Založte adresář, např. src/content/docs/publikace/, a do něj první stránku index.md.

Přidejte sekci do navigace v astro.config.mjs (pole sidebar):

{
  label: 'Publikace',
  translations: { en: 'Publishing' },
  autogenerate: { directory: 'publikace' },
},

Podrobně: Sidebar Navigation.

Lokální práce: příkaz `sdocs`

Potřebujete jen Docker — žádný Node.js, žádná platforma. Vše obsluhuje příkaz sdocs.

Jednorázová instalace:

git clone git@gitlab.solidapp.cz:solidpixels/platform-docs/docs-source.git
cd docs-source
./bin/sdocs install    # přidá sdocs do PATH + zapne našeptávání (zsh i bash)

Pak otevřete nový terminál a máte k dispozici:

Živý náhled pro editaci

sdocs up      # spustí živý náhled → http://localhost:4321
sdocs down    # zastaví všechny náhledy

Úpravy v src/content/docs/ se v prohlížeči projeví samy.

Stažení změn a kontrola rozdílů

sdocs pull    # stáhne změny ostatních z GitLabu k vám na disk
sdocs status  # co běží, co máte rozpracováno, co je ke stažení/odeslání

Finální validace, publikace a sdílení

sdocs check    # kontrola obsahu (rozbité odkazy, chybějící frontmatter…)
sdocs build    # kontrolní náhled s vyhledáváním → http://localhost:4322
sdocs send     # odešle změny do připravované dokumentace
sdocs release  # zveřejní obsah připravované dokumentace
sdocs share    # sdílený náhled rozpracované větve

Odesílá se do next.docs.solidapp.cz, zveřejňuje na docs.solidpixels.com. Adresu sdíleného náhledu vypíše příkaz sdocs share — zkopírujte ji z výpisu.

Pomocné nástroje

sdocs logs   # logy náhledů (když něco nefunguje)
sdocs clean  # smaže vygenerované soubory a zastaví kontejnery náhledů

sdocs clean maže stažené závislosti a vygenerovaný web (node_modules, .astro, dist) — obsah v src/ a neodeslané úpravy zůstávají. Použijte, když náhled nefunguje ani po sdocs down a sdocs up; další start si vše stáhne znovu.

Zapamatujte si směr: pull stahuje k vám, send odesílá do připravované dokumentace a release ji zveřejňuje. Nevíte-li, v jakém jste stavu, sdocs status odpoví.

Typický den editora:

sdocs pull      # ráno: stáhnout změny ostatních
sdocs up        # psaní se živým náhledem
sdocs build     # kontrolní náhled: vyhledávání a finální podoba
sdocs send      # odeslání změn do připravované dokumentace
sdocs down      # úklid

sdocs send před odesláním vždy spustí kontrolu a vyžádá si potvrzení; volitelně přijme popis změny: sdocs send "Doplněn návod na obrázky".

Připravovaná a zveřejněná dokumentace

Obsah putuje ve dvou krocích — nic se nezveřejní omylem:

Krok	Příkaz	Kde to uvidíte
1. Odeslání ostatním ke kontrole	`sdocs send`	připravovaná dokumentace → https://next.docs.solidapp.cz
2. Zveřejnění pro veřejnost	`sdocs release`	zveřejněná dokumentace → https://docs.solidpixels.com

Připravovaná dokumentace je plnohodnotná kopie webu, kterou vidí kolegové, ale ne zákazníci. Patří sem hotové úpravy, které čekají na zveřejnění — rozdělanou práci nechte ve vlastní rozpracované větvi a ukažte ji sdíleným náhledem (sdocs share).
Zveřejněná dokumentace (živý web) se změní až příkazem sdocs release. Ten nejdřív ukáže seznam všech změn, které by se zveřejnily, a pro jistotu si vyžádá napsání slova release (samotné „ano“ nestačí).
Obojí nasazuje CI, takže od potvrzení do zobrazení uplyne pár minut.
Sdílený náhled (sdocs share) vytvoří dočasnou veřejnou adresu vaší rozpracované větve. Je dlouhá a technická, takže ji zkopírujte z výpisu a pošlete kolegovi; není potřeba si ji pamatovat.

Kontrola před odesláním

Před vytvořením merge requestu spusťte sdocs check — odhalí rozbité odkazy na komponenty, chybějící frontmatter a chyby buildu s odkazem na soubor a řádek. Stejná kontrola běží v CI a vadný obsah zablokuje odeslání i zveřejnění.

Drobné úpravy bez lokálního prostředí

U každé stránky je odkaz Edit page, který otevře soubor přímo v GitLabu — pro opravu překlepu není potřeba nic instalovat.