A Nextra segítségével percek alatt elkészíthet egy webhelyet, így tökéletes a dokumentumok csapata számára történő terjesztésére.

Ha ismeri a Next.js-t, könnyedén elkészítheti egy dokumentációs webhelyet. A Nextra keretrendszer gondoskodik a finomságról az Ön számára; mindössze annyit kell tennie, hogy hozzáadja a Markdown vagy HTML tartalmat és a YAML vagy JSON adatokat.

Végezze el ezeket a lépéseket, és készítsen dokumentációs webhelyet a Nextra, a Next.js-alapú statikus webhelygenerátor segítségével. Telepíti és beállítja a szükséges függőségeket, majd megtanulja, hogyan adhat hozzá új dokumentumokat és oldalakat, hogyan írhat le Markdownt, és hogyan vehet fel React összetevőket.

Követelmények a következő dokumentum-webhely létrehozásához

Kezdje a Node.js telepítésével, ha még nem tette meg. A legújabb Node.js verzió az npm-mel, a csomóponti csomagkezelővel érkezik, amelyre szüksége lesz a függőségek telepítéséhez ehhez a projekthez.

A Node.js mellett telepítenie kell Git. A Gitre van szüksége ahhoz, hogy a webhelyet GitHub-oldalakra, Netlify-ra vagy más tárhelyszolgáltatóra telepítse. Szüksége lesz egy speciális kódszerkesztőre is, például a VS Code-ra.

instagram viewer

Nextra telepítése

Használhatja a nextra docs sablon egy dokumentációs webhely indításához. Indítson el egy parancssort, és keresse meg azt a könyvtárat, amelyben be szeretné állítani a projektet. Ezután futtassa a következő parancsot a dokumentációs webhely indításához:

git klón https://github.com/shuding/nextra-docs-template

Ez a parancs egy alkalmazást az aktuális könyvtárban helyez el. Ezután futtassa a következő parancsot a függőségek telepítéséhez:

cd nextra-docs-template
npm telepítés

A telepítés befejezése után indítsa el az alkalmazást. Ehhez futtassa a következő parancsot a terminálon:

npm futás dev

Ez a parancs elindít egy fejlesztőkiszolgálót a localhost: 3000 címen. A dokumentációs oldal megtekintéséhez kövesse a terminálon található hivatkozást. A kezdőlapnak így kell kinéznie:

Ha ránéz az oldal bal oldalán, megtalálja a megnevezett oldalakat Bevezetés és Egy másik oldal. Ezen oldalhivatkozások alatt talál egy Satori nevű oldalt, amely a lap belsejébe van ágyazva Speciális (A mappa) Könyvtár. Végül a navigációs területen találhat hivatkozásokat a Ról ről és Kapcsolatba lépni oldalakat.

Az oldalak működésének megértéséhez először meg kell értenie hogyan jeleníti meg a Next.js az oldalakat.

A címtárstruktúra megértése

Mivel a Nextra a Next.js keretrendszert használja, minden fájlt a oldal/ mappát külön oldalként.

Benne oldalakat könyvtárban négy sablonfájlt talál: about.mdx, fejlett.mdx, másik.mdx, és index.mdx. Ezen fájlok mindegyike a webhely egy-egy oldalának felel meg; például, index.mdx a kezdőlapnak felel meg. Az URL localhost: 3000/kb megfelel about.mdx, stb.

Belül oldalakat, van egy mappa is fejlett, amely egyetlen nevű fájlt tartalmaz satori.mdx. A fájl URL-je a következő lesz localhost: 3000/haladó/satori.

Figyelje meg, hogy ezek a fájlok hogyan végződnek a-val .mdx kiterjesztés.

Mi az MDX?

Ha van tapasztalat a React-tal, tudnia kell a JSX-ről. Ez egy HTML-szerű nyelv, amellyel leírhatja a React összetevőinek felhasználói felületét.

Az MDX betölti, elemzi és rendereli a JSX-et egy Markdown dokumentumban. Az MDX-nek köszönhetően React-összetevőket írhat, és szükség esetén importálhatja azokat Markdown-dokumentumaiba. Az MDX-fájlok .mdx kiterjesztéssel végződnek, és tartalmazhatják mind a Markdownt, mind a JSX-et.

Az MDX lehetővé teszi, hogy a Markdown-ról szerzett ismereteit egyesítse a React-tal, hogy újrafelhasználható összetevőket hozzon létre. tudsz CSS modulok létrehozása az összetevők stílusához. Ez segít az összetevők rendszerezésében az olvashatóság és a karbantarthatóság javítása érdekében.

Meglévő oldalak szerkesztése a dokumentációs oldalon

Meglévő oldal szerkesztéséhez egyszerűen nyissa meg a megfelelő fájlt, és módosítsa azt. A támogatott nyelvek a Markdown és a JSX.

Például nyissa meg a index.mdx fájlt, és cserélje ki a tartalmat erre:

# Üdvözöljük a Dokumentációmban
Örülök, hogy itt látlak. Kösz
## Saját közösségi oldalaim
Kövess engem [Twitter](https://twitter.com/kingchuuks) és [LinkedIn](https://linkedin.com/in/kingchuks)

Ez a példa a Markdown-t használja a tartalom formázásához. Tartalmaz egy első szintű címsort, egy második szintű címsort és két közösségi média hivatkozást.

Mentse el a fájlt, és keresse fel a dokumentációs webhely kezdőlapját. Az oldalnak most így kell kinéznie:

Az oldal alján a dokumentum utolsó frissítésének dátuma is megtalálható.

Új oldal hozzáadása

Mielőtt új oldalt adna hozzá, először el kell döntenie, hogy az oldal benne lesz-e oldal/ könyvtárban vagy egy azon belüli mappában. Használjon mappákat, ha kategorizálni szeretné oldalait, vagy hierarchiát szeretne kialakítani.

Ebben az esetben hozzon létre egy önálló oldalt a legfelső szinten. Nyisson meg egy nevű fájlt install.mdx a kódszerkesztőben, és illessze be a következő Markdown kódot:

# Telepítési útmutató
Kövesse ezt az útmutatót a csomagom projektbe való telepítéséhez
## 1. Telepítse a Node.js-t
A Node.js telepítéséhez keresse fel a
[Node.js dokumentációs webhely](https://nodejs.org/en/download)

Mentse el a fájlt, és ellenőrizze a böngészőt. A Telepítés címkét az oldalsó menüben találja. Ha rákattint a linkre, a tartalom install.mdx megjeleníti az oldalon:

Módosíthatja a címkét és más konfigurációkat is végrehajthat a _meta.json fájlban a pages könyvtárban. Ha többet szeretne megtudni erről, tekintse meg a Fájlok rendezése szakasza Nextra dokumentációja.

React komponensek használata

Az MDX-fájlok tartalmazhatnak JSX-et, amely a React által használt nyelv. Létrehozhat egy összetevőt az összetevők mappájában, és importálhatja a webhely bármely dokumentumába.

Példát láthat arra, hogyan ágyazhat be komponenseket a Markdownba a másik.mdx fájl:

## Összetevő
{useState} importálása a 'react'-ból
stílusok importálása innen: "../components/counters.module.css"
export const Számláló = () => { 
 const [count, setCount] = useState (0); 


 Visszatérés( 


 {count} alkalommal kattintott


)
}

<Számláló />

## Külső alkatrészek
számlálók importálása innen: "../components/counters"

<Számlálók />

Ez a Markdown fájl a Számláló összetevő definícióját tartalmazza. Ezt követően importálja a Számlálók összetevőt a alkatrészek Könyvtár.

Ha ugyanazt az összetevőt használja a dokumentációs webhelyén, akkor a legjobb, ha önálló összetevőként hozza létre, és amikor szüksége van rá, importálja.

További információ a Markdownról

A dokumentációs webhely tartalmának létrehozásához ismernie kell a Markdown használatát. A jó hír az, hogy a Markdown szintaxist meglehetősen könnyű átvenni. Ha egyesíti a Markdown-ról szerzett ismereteit a React-tal, akkor igazán robusztus dokumentációs oldalakat hozhat létre.