Nextra ви позволява да създадете сайт за минути, така че е идеален за разпространение на документи до вашия екип.

Ако сте запознати с Next.js, можете да го използвате, за да разработите лесно сайт с документация. Рамката Nextra се грижи за дребните неща вместо вас; всичко, което трябва да направите, е да добавите Markdown или HTML съдържание и YAML или JSON данни.

Преминете през тези стъпки, за да създадете сайт с документация с помощта на Nextra, генератор на статични сайтове, базиран на Next.js. Ще инсталирате и настроите необходимите зависимости, след което ще научите как да добавяте нови документи и страници, да пишете Markdown и да включвате компоненти на React.

Изисквания за изграждане на сайт за документи с Nextra

Започнете, като инсталирате Node.js, ако още не сте го направили. The най-новата версия на Node.js идва с npm, мениджърът на пакети на възли, който ще ви трябва, за да инсталирате зависимости за този проект.

Освен Node.js, ще трябва да инсталирате Git. Имате нужда от Git, за да внедрите сайта в страници на GitHub, Netlify или друг хостинг доставчик. Ще ви е необходим и усъвършенстван редактор на код, като например VS Code.

instagram viewer

Инсталиране на Nextra

Можете да използвате a шаблон за документи nextra за стартиране на сайт с документация. Стартирайте команден ред и отидете до директорията, в която искате да настроите вашия проект. След това изпълнете следната команда, за да стартирате сайта с документация:

git клонинг https://github.com/shuding/nextra-docs-template

Тази команда ще скеле приложение в текущата директория. След това изпълнете следната команда, за да инсталирате зависимостите:

cd nextra-docs-template
npm инсталирайте

След като инсталацията приключи, стартирайте приложението. Направете го, като изпълните следната команда на вашия терминал:

npm стартиране dev

Тази команда стартира сървър за разработка на localhost: 3000. Следвайте връзката на вашия терминал, за да видите сайта с документация. Началната страница трябва да изглежда така:

Ако погледнете отляво на страницата, ще намерите посочените страници Въведение и Още една страница. Под тези връзки към страници ще намерите страница с име Satori, вложена в Разширени (папка) указател. И накрая, в зоната за навигация ще намерите връзки към относно и Контакт страници.

За да разберете как работят тези страници, първо трябва да разберете как Next.js изобразява страници.

Разбиране на структурата на директорията

Тъй като Nextra използва рамката Next.js, тя изобразява всеки файл в страници/ папка като отделна страница.

Вътре в страници директория, ще намерите четири шаблонни файла: about.mdx, напреднали.mdx, друг.mdx, и index.mdx. Всеки от тези файлове съответства на страница от уебсайта; например, index.mdx съответства на началната страница. URL адресът localhost: 3000/около съответства на about.mdx, и така нататък.

Вътре страници, има и папка с име напреднал, съдържащ един файл с име сатори.mdx. URL адресът за този файл ще бъде localhost: 3000/advanced/satori.

Забележете как всеки от тези файлове завършва с a .mdx разширение.

Какво е MDX?

Ако имате опит с React, трябва да знаете за JSX. Това е HTML-подобен език, който можете да използвате, за да опишете потребителския интерфейс на компонентите на React.

MDX зарежда, анализира и изобразява JSX в Markdown документ. Благодарение на MDX можете да пишете React компоненти и да ги импортирате във вашите Markdown документи, когато е необходимо. MDX файловете завършват с разширение .mdx и могат да включват както Markdown, така и JSX.

MDX ви позволява да комбинирате знанията си за Markdown с React, за да създадете компоненти за многократна употреба. Можеш създаване на CSS модули за стилизиране на компонентите. Това ви помага да организирате вашите компоненти, за да подобрите четливостта и поддръжката.

Как да редактирате съществуващи страници в сайта за документация

За да редактирате съществуваща страница, просто отворете съответния файл и направете промени в него. Поддържаните езици са Markdown и JSX.

Например, отворете index.mdx файл и заменете съдържанието с това:

# Добре дошли в моята документация
Радвам се да те видя тук. Благодаря
## Моите социални
Следвайте ме на [Twitter](https://twitter.com/kingchuuks) и [LinkedIn](https://linkedin.com/in/kingchuks)

Този пример използва Markdown за форматиране на съдържанието. Той съдържа заглавие от първо ниво, заглавие от второ ниво и две връзки към социални медии.

Запазете файла и посетете началната страница на вашия сайт за документация. Сега страницата трябва да изглежда така:

В долната част на страницата можете да намерите и последната актуализирана дата на документа.

Добавяне на нова страница

Преди да добавите нова страница, първо трябва да решите дали страницата ще бъде в страници/ директория или в папка в нея. Използвайте папки, ако искате да категоризирате страниците си или да създадете йерархия.

В този случай създайте самостоятелна страница на най-високо ниво. Отворете файл с име инсталация.mdx във вашия редактор на код и поставете следния код Markdown в него:

# Ръководство за инсталиране
Следвайте това ръководство, за да инсталирате моя пакет във вашия проект
## 1. Инсталирайте Node.js
За да инсталирате Node.js, посетете
[Сайт с документация за Node.js](https://nodejs.org/en/download)

Запазете файла и проверете браузъра. Ще намерите етикета за инсталиране в страничното меню. Когато щракнете върху връзката, съдържанието на инсталация.mdx изобразява на страницата:

Можете да промените етикета и да извършите други конфигурации във файла _meta.json в директорията на страниците. За да научите повече за това, вижте Организиране на файлове раздел на Документация на Nextra.

Използване на компоненти на React

MDX файловете могат да включват JSX, който е езикът, който React използва. Можете да създадете компонент в папката с компоненти и да го импортирате във всеки от документите на вашия сайт.

Можете да видите пример за това как можете да вградите компоненти в Markdown в друг.mdx файл:

## Компонент
импортиране на {useState} от 'react'
импортирайте стилове от '../components/counters.module.css'
експортиране const Брояч = () => { 
 const [count, setCount] = useState (0); 


 връщане( 


 Кликване {count} пъти


)
}

<Брояч />

## Външни компоненти
импортиране на броячи от '../components/counters'

<Броячи />

Този файл Markdown съдържа дефиниция за компонента Counter. След това той импортира компонента Counters от компоненти указател.

Ако възнамерявате да използвате един и същ компонент във вашия сайт за документация, най-добре е да го създадете като самостоятелен компонент и да го импортирате, когато имате нужда от него.

Научете повече за Markdown

За да създадете съдържание за вашия сайт с документация, трябва да знаете как да използвате Markdown. Добрата новина е, че синтаксисът на Markdown е доста лесен за разбиране. Когато комбинирате знанията си за Markdown с React, можете да създадете наистина стабилни сайтове за документация.