Jak psát moudra

Jak tvořit obsah

K tvoření obsahu pro klobouk si ve většině případů vystačíte jen s textovým, nebo markdown editorem. Pro tvorbu “klobouku” je použít framework Starlight, který nám umožnuje generovat stránky s návody z .md, nebo .mdx souborů. Většinu formátování tak dokážeme zajistit snadno v textu pomocí značkovacího jazyka Markdown. Pro případy kdy si Markdownem nevystačíme však umožňuje i použití vlastních komponent, nebo přímé použití HTML.

Formátování textu

Odstavec

Odstavec v md není potřeba nijak zvlášť označovat. Jedná se o jeden či více souvislých řádku textu. Další odstavec oddělujeme jedním či více “prázdnými řádky” (“řádkem obsahujícím pouze mezery či taby).

První
odstavec
textu

Druhý odstavec textu

Tučné

Tučný text je možné docílit obalením daného textu dvojicí asterisků či podtržítek **tučný** bude vypadat stejně jako __text__

Kurzíva

Text Kurzívou je možné docílit obalením daného textu jedním asteriskem či podtržítkem *Text* bude vypadat stejně jako _kurzívou_

Jak křížit tučný text s kurzívou?

Je to jednodušší než čekáte, stačí použít tři podtržítka či asterisky. ___jednodušší___ než ***čekáte***

Proškrtnutí

Proškrtnutí textu je možné docílit obalením daného textu dvojicí znaku “tilda”. ~~Proškrtnutý text~~

Citace

Blok citace v textu označujeme ostrou závorkou na začátku každého řádku, který má citace obsahovat.

Pro vnořenou citaci je možné znak opakovat.

> Blok citace v textu označujeme ostrou závorkou
> na začátku každého řádku, který má citace obsahovat.
>> Pro vnořenou citaci je možné znak opakovat.

Zvýraznění “kódu”

V textu můžeme zvýraznit znaky neproporciálním písmem obalením do zpětných uvozovek. znaky `neproporciálním` písmem

Pro označení bloku textu se využívá obalením do trojice zpětných uvozovek. Pozor oproti příkladu je potřeba aby každá trojice byla na samostatném řádku.

```Lorem ipsum dolor whatever```

Nadpis

Hlavičky H1 až H6 označíme znakem hash # před nadpisem. Kdy počet použitých znaků udává úroveň nadpisu.

# Nadpis H1
## Nadpis H2
### Nadpis H3
#### Nadpis H4
##### Nadpis H5
###### Nadpis H6

Pro nadpis první a druhé úrovně je možné ještě alternativně využít podtržením znaky = a -

Nadpis H1
=========

Nadpis H2
---------

Seznamy

Nečíslovaný seznam

Odrážky nečíslovaného seznamu můžeme vytvářet pomlčkou nebo asteriskem na počátku řádku. Více úrovní je možné využít použitím tabulátoru.

* Příklad
Nějakého
* Nečíslovaného
  - Seznamu

• Příklad Nějakého
• Nečíslovaného
  • Seznamu

Číslovaný seznam

Číslovaný seznam vytváříme uvedením čísla tečky a mezery na počátku řádku. Samotné číslo se nezohledňuje.

1. První
1. Druhý
   1. Další úroveň
      * Další nečíslovaná úroveň

1. První
2. Druhý
   1. Další úroveň
      • Další nečíslovaná úroveň

Číslované a nečíslované seznamy můžeme pro různé úrovně kombinovat. Viz předchozí příklad.

Checklist

• A
• B
• A
• B
• C

- [ ] A
- [ ] B
- [x] A
- [x] B
- [x] C

Odkaz

Odkaz se do textu vkládá kombinací dvojice hranatých a kulatých závorek. První obsahuje text odkazu a druhý samotný link.

[Odkaz](http://www.zvb.cz)

Interní odkazy můžeme využívat na obsah v rámci klobouku.

[Interní odkazy](/other/sprava-obsahu-github)

Reference

Příklad věty s referencí. ¹

Příklad věty s referencí. [^1]

[^1]: Toto je reference z příkladu.

Obrázek

Obrázky mají podobnou notaci jako odkazy. Předchází je vykřičník a text v hranatých závorkách by měl být popisem obrázku. Pro obrázky v src/assets/images použijeme alias @images, takže odkaz nezávisí na umístění stránky.

![Popis obrázku](@images/nazev-souboru.png)

![Status](http://navody.zvb.cz/img/status.PNG)

Jak na zmenšený obrázek s proklikem?

K tomu můžeme využít kombinace notace pro odkaz, kde místo textu vložíme html tag obrázku.

[<img src="http://navody.zvb.cz/img/2.png" width="450"/>](http://navody.zvb.cz/img/2.png)

Tabulkas

| Hlavička vlevo | Hlavička vpravo | Hlavička střed |
|----------------|----------------:|:--------------:|
| Obsah vlevo    |    Obsah vpravo |  Obsah střed   |
| Obsah vlevo    |    Obsah vpravo |  Obsah střed   |
| Obsah vlevo    |    Obsah vpravo |  Obsah střed   |

Hlavička vlevo	Hlavička vpravo	Hlavička střed
Obsah vlevo	Obsah vpravo	Obsah střed
Obsah vlevo	Obsah vpravo	Obsah střed
Obsah vlevo	Obsah vpravo	Obsah střed

Rozdělovač

---

Rozdělovač textu vkládáme trojicí znaku pomlčky.

---

---

Rozdělovač textu vkládáme trojicí znaku pomlčky

---

Pozor

Pokud chceme následovat rozdělovačem pod textem, tak je nutné vynechat jeden volný řádek. V jiném případě by se z textu stal nadpis druhé úrovně.

Aside

Barevným boxíkům, kterých už jste si mohli všimnout výše, budeme říkat aside. Notace pro jejich použití nění součástí markdownu a proto se vám mimo klobouk hezky nezobrazí. Starlight umožňuje čtyři typy Aside a to tip, note, caution a danger, které se liší barvou, ikonkou a defaultním textem. Obsahem Aside může být libovolný markdown obsah, ale nejlépe se hodí na kratší poznámky a informace. Aside je možné využít i s custom nadpisem. Ten je potřeba dát do hranatých závorek ihned za typ.

:::tip
:::note
:::caution
:::danger
:::tip[Tip s custom nadpisem]
Příklad obsahu ![Status](http://navody.zvb.cz/img/status.PNG)
:::

:::idea
blik cvak
:::

:::faq
často kladená otázka
:::

Tip s custom nadpisem

Poznámka

Upozornění

Nebezpečí

Tip

Příklad obsahu

Idea

blik cvak

FAQ

často kladená otázka

Komponenty

Komponenty jsou přepoužitelné UI funkce, které je možné využívat v rámci mdx dokumentů. Některé z nich jsou již součástí Starlight. Další si možná vytvoříme.

Pro použití komponenty v rámci dokumentu je potřeba ji nějdříve importovat na začátku dokumentu (ovšem až po frontmatter sekci).

src/content/docs/index.mdx

---
title: Welcome to my docs
---

import SomeComponent from '../../components/SomeComponent.astro';
import AnotherComponent from '../../components/AnotherComponent.astro';

<SomeComponent prop="something" />

<AnotherComponent>
  Components can also contain **nested content**.
</AnotherComponent>

Pozor na příponu souboru

Aby bylo možné komponenty využívat je potřeba aby měl dokument příponu .mdx

Taby

Jídlo

Polévka, Kaše, Maso

Pití

Džus, Víno, Čaj

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="Jídlo">Polévka, Kaše, Maso</TabItem>
  <TabItem label="Pití">Džus, Víno, Čaj</TabItem>
</Tabs>

Užitečné doplnění

<Tabs> umí i syncKey, takže lze propojit více skupin tabů napříč stránkou. <TabItem> navíc podporuje icon, pokud chcete k názvu tabu přidat ikonku.

Windows

Postup pro Windows

macOS

Postup pro macOS

Windows

Doporučená zkratka: Ctrl + K

macOS

Doporučená zkratka: Cmd + K

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs syncKey="platforma">
  <TabItem label="Windows" icon="seti:windows">Postup pro Windows</TabItem>
  <TabItem label="macOS" icon="laptop">Postup pro macOS</TabItem>
</Tabs>

<Tabs syncKey="platforma">
  <TabItem label="Windows" icon="seti:windows">Doporučená zkratka: <code>Ctrl + K</code></TabItem>
  <TabItem label="macOS" icon="laptop">Doporučená zkratka: <code>Cmd + K</code></TabItem>
</Tabs>

Karta a karetní mřížka

Titulek karty

Obsah karty.

Hvězdy

Sirius, Vega, Betelgeuse

Měsíce

Io, Europa, Ganymede

Karta s odkazem Popis karty s odkazem

import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';

<Card title="Titulek karty">Obsah karty.</Card>

<CardGrid>
    <Card title="Hvězdy" icon="star">
        Sirius, Vega, Betelgeuse
    </Card>
    <Card title="Měsíce" icon="moon">
        Io, Europa, Ganymede
    </Card>
    <LinkCard
        title="Karta s odkazem"
        description="Popis karty s odkazem"
        href="../../other/sprava-obsahu-github"
    />
</CardGrid>

Ikonky

Starlight v základu obsahuje několik základních ikonek, které je možné využívet s <Icon> Komponentou

import { Icon } from '@astrojs/starlight/components';

<Icon name="star" color="goldenrod" size="2rem" />

Kde najít všechny ikonky?

Všechny ikonky je možné najít na odkazu zde

Lightbox

Pro lokální obrázky můžeme využít komponentu Lightbox, která obrázek automaticky zmenší na šířku obsahu a po kliknutí jej zobrazí ve větším náhledu.

import Lightbox from '@components/Lightbox.astro';

<Lightbox src="@images/Page.png" alt="Ukázkový obrázek" />

Tooltip

Tooltip zvýrazní krátký pojem podobně jako odkaz a po najetí myší nebo zaměření klávesnicí zobrazí vysvětlení.

Kouzelnická škola Bradavice Škola čar a kouzel založená před více než tisíci lety. leží ve Skotsku.

import Tooltip from '@components/Tooltip.astro';

Kouzelnická škola <Tooltip tip="Škola čar a kouzel založená před více než tisíci lety.">Bradavice</Tooltip> leží ve Skotsku.

Pro odkaz na stránku, která ještě neexistuje, použijeme kratší komponentu MissingPage. Tooltip automaticky nabídne odkaz na návod k napsání článku.

Navštivte Hampton Court Green Samostatná stránka zatím není k dispozici. Chceš pomoci s psaním článku na wiki? .

import MissingPage from '@components/MissingPage.astro';

Navštivte <MissingPage>Hampton Court Green</MissingPage>.

HoverCard

HoverCard zobrazí větší kartu s volitelným titulkem, popisem, obrázkem a odkazem.

K opakovaným činnostem můžeme využít makra Makra a makrování Krátké příkazy pro rychlé provedení opakovaných činností. Otevřít stránku .

import HoverCard from '@components/HoverCard.astro';

<HoverCard
  title="Makra a makrování"
  description="Krátké příkazy pro rychlé provedení opakovaných činností."
  image="@images/makro.png"
  imageAlt="Nastavení makra"
  href="/system/makra">makra</HoverCard>

Pro interní stránku stačí href a vlastnost preview. Titulek, popis a případný obrázek se načtou z frontmatter cílové stránky během buildu.

Přečtěte si více o KAVKU Královská akademie věd, kouzel a umění Nejstarší magická výzkumná instituce na Britských ostrovech, ukrytá v lesích Gloucestershiru, která se věnuje magickému výzkumu, výuce a kulturním akcím jako slavné KAVKU Gala. Otevřít stránku .

<HoverCard href="/lore/magicke-instituce/kavku" preview>
  KAVKU
</HoverCard>

FileTree

• Adresářsrc

  • Adresářcomponents

    • Header.astro

import { FileTree } from '@astrojs/starlight/components';

<FileTree>
- src
  - components
    - Header.astro
</FileTree>

Steps

1. Krok první
2. Krok druhý

import { Steps } from '@astrojs/starlight/components';

<Steps>
1. Krok první
2. Krok druhý
</Steps>

LinkButton

Správa obsahu

import { LinkButton } from '@astrojs/starlight/components';

<LinkButton href="../../other/sprava-obsahu-github">Správa obsahu</LinkButton>

Tlačítko může mít také variant, icon a iconPlacement.

Dokumentace Starlight

import { LinkButton } from '@astrojs/starlight/components';

<LinkButton
  href="https://starlight.astro.build/"
  variant="secondary"
  icon="external"
  iconPlacement="start"
>
  Dokumentace Starlight
</LinkButton>

Badge

Nové

import { Badge } from '@astrojs/starlight/components';

<Badge text="Nové" variant="success" />

Badge podporuje i size a běžné HTML atributy jako class nebo style.

Novinka

import { Badge } from '@astrojs/starlight/components';

<Badge text="Novinka" variant="tip" size="large" />

Code

console.log('Ahoj')

import { Code } from '@astrojs/starlight/components';

<Code code={`console.log('Ahoj')`} lang="js" />

StarlightPage a AnchorHeading

Tyto komponenty dávají největší smysl v .astro stránkách v src/pages/, když chcete použít vzhled Starlightu i mimo běžné .md / .mdx dokumenty. Pro obyčejné články v markdownu obvykle stačí běžné nadpisy ## a ###, protože Starlight k nim anchor odkazy přidá automaticky.

---
import StarlightPage from '@astrojs/starlight/components/StarlightPage.astro';
import AnchorHeading from '@astrojs/starlight/components/AnchorHeading.astro';
---

<StarlightPage frontmatter={{ title: 'Moje stránka' }}>
    <AnchorHeading level="2" id="nadpis">Nadpis</AnchorHeading>
    <p>Obsah stránky</p>
</StarlightPage>

Frontmatter

Frontmatter je část souboru, která se nachází před samotným obsahem souboru. Obvykle se používá k ukládání metadat o souboru, jako je název souboru, autor, datum vytvoření a další. V tomto dokumentu vypadá následovně:

---
title: Jak psát moudra
description: Nápověda k tomu jak poskytnout svůj vlastní obsah
---

V rámci Starlight je povinnou součástí každeho md / mdx souboru a musí obsahovat minimálně položku title. Ostatní parametry jsou nepovinné, ale umožňují nám ovlivnit chování jednotlivých dokumentů.

Pro naše použití níže uvedu pouze ty nejdůležitější. Všechny parametry je možné najít na odkazu zde.

title

Jedná se o povinný parametr pro každý dokument. Využívá se jako hravní titulek, název v tabu prohlížeče a metadata stránky.

description

Používá se pro metadata stránky a poskytuje vyhledávácí data pro vyhledávací enginy.

slug

Umožňuje přepsat výslednou URL stránky bez nutnosti přesouvat soubor v adresářové struktuře.

---
title: Článek se zkrácenou adresou
slug: zkracena-adresa
---

Typicky se hodí ve chvíli, kdy chcete zachovat starý odkaz na článek i po přejmenování souboru.

tableOfContents

Dokáže pro stránku změnit globální nastavení pro tabulku s obsahem dokumentu.

Příklad vypnutí obsahu

---
title: Stránka bez obsahu
tableOfContents: false
---

Příklad změny úrovně nadpisů v obsahu

title: Stránka pouze s H2 nadpisy
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2

template

Určuje šablonu rozložení stránky. Může mít hodnoty doc (viz tento dokument) nebo splash (úvodní stánka klobouku, bez sidebarů).

hero

Umístí Hero komponentu na počátek stránky. Viz úvodní stránka klobouku. Varianta tlačítek je nyní ve výchozím stavu primary, takže není nutné ji nastavovat, pokud ji nechcete změnit.

---
title: Úvod
template: splash
hero:
  title: 'Nějakej nadpis'
  tagline: Něco pod tím.
  image:
    alt: Hustý logo
    file: ../../assets/logo.png
  actions:
    - text: Text primárního tlačítka
      link: odkaz-buttonu/
      icon: right-arrow
    - text: Text druhého buttonu
      link: https://github.com/astronaut/my-project
      icon: external
---

banner

Slouží pro zobrazení banneru na vrchu stránky.

---
title: Page with a banner
banner:
  content: Tady je můj cool banner
---

prev a next

Ovlivňují chování “předchozího” a “následujícího” odkazu na konci dokumentů.

Příklad vypnutí předchozího odkazu

---
title: Stránka bez obsahu
prev: false
---

Příklad změny směřování

---
title: Stránka pouze s H2 nadpisy
prev:
  link: jina-stranka/
  label: Jiný titulek
---

pagefind

Určuje zda je tato stánka vyhledatelná pomocí hledání. Hodnota je true / false

sidebar

Ovlivňuje chování sidebaru pokud je pro tuto stránku automaticky vygenerovaný odkaz. Platí pro odkazy ze slug nebo z automaticky generovaných skupin, ne pro položky sidebaru zapsané natvrdo přes link.

interface SidebarConfig {
  label?: string;
  order?: number;
  hidden?: boolean;
  badge?: string | BadgeConfig;
  attrs?: Record<string, string | number | boolean | undefined>;
}

label

Součást sidebar. Určuje popisek stránky v sidebaru pokud je pro tuto stránku automaticky vygenerovaný odkaz.

order

Součást sidebar. Určuje pořadí stránky v sidebaru pokud je pro tuto stránku automaticky vygenerovaný odkaz. Nižší číslo řadí stránku výše.

hidden

Součást sidebar. Zabraňuje aby byla tato stránka přidána do automaticky vygenerovaných odkazů v sidebaru.

badge

Součást sidebar. Mění chování (zobrazení) badge u odkazu této stránky v sidebaru

---
title: Stránka s badge
sidebar:
  badge: New
---

---
title: Page with a badge
sidebar:
  badge:
    text: Experimental
    variant: caution
---

interface BadgeConfig {
  text: string;
  variant: 'note' | 'tip' | 'caution' | 'danger' | 'success' | 'default';
  class?: string;
}

Poznámka k novějším verzím

Od Starlight 0.39.0 už nelze používat autogenerate objekt zároveň s vlastním label na stejné úrovni v astro.config.mjs. Pokud chcete vlastní nadpis skupiny, použijte obalující skupinu s items: [{ autogenerate: ... }].

attrs

Součást sidebar. Přidává html atributy k automaticky vygenerovanému odkazu. Například otevření odkazu v novém tabu.

---
title: Stránka otvírající se v novém tabu
sidebar:
  attrs:
    target: _blank
---

---
title: Článek se zvýrazněním v sidebaru
sidebar:
  label: Doporučené čtení
  order: 1
  badge:
    text: Nové
    variant: tip
---

Na co si dát pozor v aktuálním Starlightu

Při psaní obsahu se dnes nejčastěji hodí myslet na tyto věci:

• Markdown bloky kódu renderuje Expressive Code, takže běžné fenced code blocky vypadají lépe i bez vlastních úprav.
• Starlight má dost vestavěných komponent pro běžnou dokumentaci: taby, kroky, karty, tlačítka, badge i file tree. Často není potřeba psát vlastní komponentu.
• sidebar frontmatter funguje hlavně pro automaticky generované skupiny a odkazy vedené přes slug.
• Pokud chcete vlastní URL, použijte slug, ne přesouvání souborů jen kvůli adrese.
• Splash stránky (template: splash) se hodí pro rozcestníky a landing page obsah s hero sekcí a výraznými CTA tlačítky.
• V astro.config.mjs už nelze kombinovat vlastní label a autogenerate v jedné položce sidebaru. Pro pojmenovanou auto-generovanou sekci použijte obalující group s items.
• Pro vlastní Astro stránky mimo obsahové kolekce je možné použít <StarlightPage> a <AnchorHeading>, ale tyto stránky se nechovají stejně jako běžné .md / .mdx dokumenty v automatickém sidebaru.

Náhled změn v pull requestu

Každý otevřený pull request se automaticky zbuildí a nasadí na testovací server. Workflow použije příznak --base s cestou ve tvaru /previews/pr-<číslo PR>, takže se správně načtou obrázky i styly. Odkaz na náhled se objeví jako komentář v pull requestu.

Chcete-li si stejný build vyzkoušet lokálně, spusťte

npm run build -- --base /previews/pr-123

a obsah z adresáře dist nahrajte na libovolný server například pomocí scp.

Footnotes

1. Toto je reference z příkladu. ↩