Vytvořte si web Doc s Next.js pomocí Nextra

Pokud znáte Next.js, můžete jej snadno použít k vývoji webu s dokumentací. Rámec Nextra se za vás postará o to nejnutnější; vše, co musíte udělat, je přidat obsah Markdown nebo HTML a data YAML nebo JSON.

Projděte si tyto kroky a vytvořte dokumentační web pomocí Nextra, generátoru statického webu založeného na Next.js. Nainstalujete a nastavíte potřebné závislosti a poté se naučíte přidávat nové dokumenty a stránky, psát Markdown a zahrnout komponenty React.

Požadavky na vytvoření webu Doc s Nextra

Začněte instalací Node.js, pokud jste tak ještě neučinili. The nejnovější verzi Node.js přichází s npm, správcem balíčků uzlů, který budete potřebovat k instalaci závislostí pro tento projekt.

Kromě Node.js budete muset nainstalovat Git. K nasazení webu na stránky GitHub, Netlify nebo jiného poskytovatele hostingu potřebujete Git. Budete také potřebovat pokročilý editor kódu, jako je VS Code.

Instalace Nextry

Můžete použít a šablona nextra docs k zavedení webu s dokumentací. Spusťte příkazový řádek a přejděte do adresáře, ve kterém chcete nastavit svůj projekt. Poté spusťte následující příkaz pro zavedení webu s dokumentací:

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

Tento příkaz vytvoří lešení aplikace v aktuálním adresáři. Dále spusťte následující příkaz k instalaci závislostí:

cd nextra-docs-template
instalace npm

Po dokončení instalace spusťte aplikaci. Udělejte to spuštěním následujícího příkazu na vašem terminálu:

npm spustit dev

Tento příkaz spustí vývojový server na localhost: 3000. Kliknutím na odkaz na vašem terminálu zobrazíte stránku dokumentace. Domovská stránka by měla vypadat takto:

Pokud se podíváte na levou stranu stránky, najdete pojmenované stránky Úvod a Další stránka. Pod těmito odkazy na stránky najdete stránku s názvem Satori, vnořenou uvnitř Pokročilé (složka A) adresář. Nakonec v navigační oblasti najdete odkazy na O a Kontakt stránky.

Abyste pochopili, jak tyto stránky fungují, musíte nejprve porozumět jak Next.js vykresluje stránky.

Pochopení adresářové struktury

Protože Nextra používá rámec Next.js, vykresluje každý soubor v stránky/ složku jako samostatnou stránku.

Uvnitř stránky adresář, najdete čtyři soubory šablon: o.mdx, pokročilé.mdx, jiný.mdx, a index.mdx. Každý z těchto souborů odpovídá stránce na webu; například, index.mdx odpovídá domovské stránce. Adresa URL localhost: 3000/asi odpovídá o.mdx, a tak dále.

Uvnitř stránky, je zde také složka s názvem pokročilý, obsahující jediný soubor s názvem satori.mdx. Adresa URL tohoto souboru bude localhost: 3000/pokročilý/satori.

Všimněte si, jak každý z těchto souborů končí a .mdx rozšíření.

Co je MDX?

Pokud máte zkušenosti s Reactem, měli byste vědět o JSX. Toto je jazyk podobný HTML, který můžete použít k popisu uživatelského rozhraní komponent React.

MDX načte, analyzuje a vykreslí JSX v dokumentu Markdown. Díky MDX můžete psát komponenty React a v případě potřeby je importovat do dokumentů Markdown. Soubory MDX končí příponou .mdx a mohou zahrnovat Markdown i JSX.

MDX vám umožní spojit vaše znalosti Markdown s Reactem a vytvořit znovu použitelné komponenty. Můžeš vytvářet CSS moduly stylizovat komponenty. To vám pomůže uspořádat vaše komponenty a zlepšit čitelnost a udržovatelnost.

Jak upravit existující stránky na webu dokumentace

Chcete-li upravit existující stránku, jednoduše otevřete odpovídající soubor a proveďte v něm změny. Podporované jazyky jsou Markdown a JSX.

Otevřete například index.mdx soubor a nahraďte obsah tímto:

# Vítejte v mé dokumentaci
Jsem rád, že tě tu vidím. dík
## Moje sociální sítě
Následuj mě na [Cvrlikání](https://twitter.com/kingchuuks) a [LinkedIn](https://linkedin.com/in/kingchuks)

Tento příklad používá Markdown k formátování obsahu. Obsahuje nadpis první úrovně, nadpis druhé úrovně a dva odkazy na sociální sítě.

Uložte soubor a navštivte domovskou stránku vašeho webu s dokumentací. Stránka by nyní měla vypadat takto:

V dolní části stránky také naleznete datum poslední aktualizace dokumentu.

Přidání nové stránky

Před přidáním nové stránky se musíte nejprve rozhodnout, zda bude stránka v stránky/ adresář nebo uvnitř složky v něm. Pokud chcete kategorizovat stránky nebo vytvořit hierarchii, použijte složky.

V tomto případě vytvořte samostatnou stránku na nejvyšší úrovni. Otevřete soubor s názvem instalace.mdx ve svém editoru kódu a vložte do něj následující kód Markdown:

# Průvodce instalací
Podle tohoto průvodce nainstalujte můj balíček do vašeho projektu
## 1. Nainstalujte Node.js
Chcete-li nainstalovat Node.js, navštivte
[Dokumentační web Node.js](https://nodejs.org/en/download)

Uložte soubor a zkontrolujte prohlížeč. V postranní nabídce najdete štítek Instalace. Když kliknete na odkaz, obsah instalace.mdx vykresluje na stránce:

Můžete změnit štítek a provést další konfigurace v souboru _meta.json v adresáři pages. Chcete-li se o tom dozvědět více, viz Uspořádat soubory sekce Dokumentace Nextry.

Použití komponent React

Soubory MDX mohou obsahovat JSX, což je jazyk, který React používá. Komponentu můžete vytvořit ve složce komponent a importovat ji do libovolného dokumentu na vašem webu.

Můžete vidět příklad toho, jak můžete vložit komponenty do Markdown v jiný.mdx soubor:

## Komponent
import {useState} z 'react'
importovat styly z '../components/counters.module.css'
export const Counter = () => { 
 const [počet, setCount] = useState (0); 
 vrátit se( 

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