Vytvorte si stránku Doc s Next.js pomocou Nextra

Ak poznáte Next.js, môžete ho ľahko použiť na vývoj dokumentačnej stránky. Rámec Nextra sa za vás postará o to, aby ste mali čo robiť. všetko, čo musíte urobiť, je pridať obsah Markdown alebo HTML a údaje YAML alebo JSON.

Prejdite si tieto kroky a vytvorte dokumentačnú lokalitu pomocou Nextra, generátora statickej lokality založenom na Next.js. Nainštalujete a nastavíte potrebné závislosti a potom sa naučíte, ako pridať nové dokumenty a stránky, napísať Markdown a zahrnúť komponenty React.

Požiadavky na vytvorenie stránky dokumentov s Nextrou

Začnite inštaláciou Node.js, ak ste tak ešte neurobili. The najnovšiu verziu Node.js prichádza s npm, správcom balíkov uzlov, ktorý budete potrebovať na inštaláciu závislostí pre tento projekt.

Okrem Node.js budete musieť nainštalovať Git. Na nasadenie lokality na stránky GitHub, Netlify alebo iného poskytovateľa hostingu potrebujete Git. Budete tiež potrebovať pokročilý editor kódu, napríklad VS Code.

Inštalácia Nextry

Môžete použiť a šablóna nextra docs na zavedenie stránky s dokumentáciou. Spustite príkazový riadok a prejdite do adresára, v ktorom chcete nastaviť svoj projekt. Potom spustite nasledujúci príkaz na zavedenie stránky dokumentácie:

git klon https://github.com/shuding/nextra-docs-template

Tento príkaz vytvorí lešenie aplikácie v aktuálnom adresári. Potom spustite nasledujúci príkaz na inštaláciu závislostí:

cd nextra-docs-template
inštalácia npm

Po dokončení inštalácie spustite aplikáciu. Urobte to spustením nasledujúceho príkazu na vašom termináli:

npm spustiť dev

Tento príkaz spustí vývojový server na localhost: 3000. Kliknutím na odkaz na vašom termináli zobrazíte stránku s dokumentáciou. Domovská stránka by mala vyzerať takto:

Ak sa pozriete na ľavú stranu stránky, nájdete stránky s názvom Úvod a Ďalšia stránka. Pod týmito odkazmi na stránky nájdete stránku s názvom Satori, vnorenú do Pokročilé (priečinok A) adresár. Nakoniec v navigačnej oblasti nájdete odkazy na O a Kontakt stránky.

Aby ste pochopili, ako tieto stránky fungujú, musíte najprv porozumieť ako Next.js vykresľuje stránky.

Pochopenie adresárovej štruktúry

Keďže Nextra používa rámec Next.js, vykresľuje každý súbor v strany/ priečinok ako samostatná stránka.

Vnútri stránky adresár, nájdete štyri súbory šablón: o.mdx, pokročilé.mdx, iný.mdx, a index.mdx. Každý z týchto súborov zodpovedá stránke na webovej lokalite; napríklad, index.mdx zodpovedá domovskej stránke. URL localhost: 3000/asi sa viaže na o.mdx, a tak ďalej.

Vnútri stránky, je tam aj priečinok s názvom pokročilé, ktorý obsahuje jeden súbor s názvom satori.mdx. Adresa URL tohto súboru bude localhost: 3000/pokročilých/satori.

Všimnite si, ako každý z týchto súborov končí na a .mdx rozšírenie.

Čo je MDX?

Ak máte skúsenosti s Reactom, mali by ste vedieť o JSX. Toto je jazyk podobný HTML, ktorý môžete použiť na opis používateľského rozhrania komponentov React.

MDX načíta, analyzuje a vykreslí JSX v dokumente Markdown. Vďaka MDX môžete písať komponenty React a v prípade potreby ich importovať do dokumentov Markdown. Súbory MDX končia príponou .mdx a môžu obsahovať Markdown aj JSX.

MDX vám umožňuje skombinovať vaše znalosti o Markdown s Reactom a vytvárať znovu použiteľné komponenty. Môžeš vytvárať CSS moduly na štýl komponentov. To vám pomôže usporiadať komponenty, aby sa zlepšila čitateľnosť a udržiavateľnosť.

Ako upraviť existujúce stránky na stránke dokumentácie

Ak chcete upraviť existujúcu stránku, jednoducho otvorte príslušný súbor a vykonajte v ňom zmeny. Podporované jazyky sú Markdown a JSX.

Otvorte napríklad index.mdx súbor a nahraďte obsah týmto:

# Vitajte v mojej dokumentácii
Som rád, že ťa tu vidím. Vďaka
## Moje sociálne siete
Nasleduj ma [Twitter](https://twitter.com/kingchuuks) a [LinkedIn](https://linkedin.com/in/kingchuks)

Tento príklad používa Markdown na formátovanie obsahu. Obsahuje nadpis prvej úrovne, nadpis druhej úrovne a dva odkazy na sociálne siete.

Uložte súbor a navštívte domovskú stránku vašej dokumentačnej lokality. Stránka by teraz mala vyzerať takto:

V spodnej časti stránky nájdete aj dátum poslednej aktualizácie dokumentu.

Pridanie novej stránky

Pred pridaním novej stránky sa musíte najprv rozhodnúť, či bude stránka v strany/ v adresári alebo v priečinku v ňom. Ak chcete kategorizovať svoje stránky alebo vytvoriť hierarchiu, použite priečinky.

V tomto prípade vytvorte samostatnú stránku na najvyššej úrovni. Otvorte súbor s názvom inštalácia.mdx v editore kódu a vložte doň nasledujúci kód Markdown:

# Návod na inštaláciu
Podľa tohto návodu nainštalujte môj balík do svojho projektu
## 1. Nainštalujte Node.js
Ak chcete nainštalovať Node.js, navštívte stránku
[Stránka s dokumentáciou Node.js](https://nodejs.org/en/download)

Uložte súbor a skontrolujte prehliadač. Štítok Inštalácia nájdete v bočnom menu. Keď kliknete na odkaz, obsah inštalácia.mdx vykresľuje na stránke:

Môžete zmeniť štítok a vykonať ďalšie konfigurácie v súbore _meta.json v adresári pages. Ak sa chcete dozvedieť viac o tom, pozrite si Usporiadať súbory časť Dokumentácia Nextry.

Používanie komponentov React

Súbory MDX môžu obsahovať JSX, čo je jazyk, ktorý React používa. Komponent môžete vytvoriť v priečinku komponentov a importovať ho do ktoréhokoľvek z dokumentov na vašej lokalite.

Môžete vidieť príklad toho, ako môžete vložiť komponenty do Markdown v iný.mdx súbor:

## Komponent
importovať {useState} z 'react'
importovať štýly z '../components/counters.module.css'
export const Counter = () => { 
 const [count, setCount] = useState (0); 
 vrátiť ( 

 setCount (count+1)} className={styles.counter}> 
 Kliknuté {count}-krát