Nextra позволяет создать сайт за считанные минуты, поэтому он идеально подходит для распространения документации среди вашей команды.

Если вы знакомы с Next.js, вы можете легко использовать его для разработки сайта документации. Фреймворк Nextra позаботится обо всем за вас; все, что вам нужно сделать, это добавить содержимое Markdown или HTML и данные YAML или JSON.

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

Требования для создания сайта документации с помощью Nextra

Начните с установки Node.js, если вы еще этого не сделали. последняя версия Node.js поставляется с npm, диспетчером пакетов узлов, который вам понадобится для установки зависимостей для этого проекта.

Помимо Node.js, вам необходимо установить Гит. Вам нужен Git для развертывания сайта на страницах GitHub, Netlify или у другого хостинг-провайдера. Вам также понадобится расширенный редактор кода, такой как VS Code.

instagram viewer

Установка Nextra

Вы можете использовать шаблон документации nextra для загрузки сайта документации. Запустите командную строку и перейдите в каталог, в котором вы хотите настроить свой проект. Затем выполните следующую команду, чтобы загрузить сайт документации:

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

Эта команда создаст шаблон приложения внутри текущего каталога. Затем выполните следующую команду для установки зависимостей:

cd nextra-docs-шаблон
установка нпм

После завершения установки запустите приложение. Сделайте это, выполнив следующую команду на своем терминале:

нпм запустить разработчик

Эта команда запускает сервер разработки на локальном хосте: 3000. Перейдите по ссылке на вашем терминале, чтобы просмотреть сайт документации. Домашняя страница должна выглядеть так:

Если вы посмотрите на левую сторону страницы, вы найдете страницы с названием Введение и Другая страница. Ниже этих ссылок на страницы вы найдете страницу под названием Satori, вложенную в Дополнительно (папка) каталог. Наконец, в области навигации вы найдете ссылки на О и Контакт страницы.

Чтобы понять, как работают эти страницы, сначала нужно понять как Next.js отображает страницы.

Понимание структуры каталогов

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

Внутри страницы каталоге вы найдете четыре файла шаблонов: о.mdx, расширенный.mdx, другой.mdx, и index.mdx. Каждый из этих файлов соответствует странице на сайте; например, index.mdx соответствует главной странице. URL-адрес локальный хост: 3000/около соответствует о.mdx, и так далее.

Внутри страницы, там также есть папка с именем передовой, содержащий один файл с именем сатори.mdx. URL этого файла будет локальный: 3000/дополнительно/сатори.

Обратите внимание, что каждый из этих файлов заканчивается .mdx расширение.

Что такое MDX?

Если у вас есть опыт работы с React, вы должны знать о JSX. Это HTML-подобный язык, который вы можете использовать для описания пользовательского интерфейса компонентов React.

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

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

Как редактировать существующие страницы на сайте документации

Чтобы отредактировать существующую страницу, просто откройте соответствующий файл и внесите в него изменения. Поддерживаемые языки: Markdown и JSX.

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

# Добро пожаловать в мою документацию
Я рад видеть вас здесь. Спасибо
## Мои социальные сети
Следуйте за мной на [Твиттер](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 в каталоге pages. Чтобы узнать больше об этом, см. Организация файлов часть Документация Nextra.

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

Файлы MDX могут включать JSX, язык, который использует React. Вы можете создать компонент внутри папки компонентов и импортировать его в любой из документов на вашем сайте.

Вы можете увидеть пример того, как вы можете встроить компоненты в Markdown в другой.mdx файл:

## Компонент
импортировать {useState} из «реагировать»
импортировать стили из '../components/counters.module.css'
экспорт константного счетчика = () => { 
 const [количество, setCount] = useState (0); 


 возвращаться( 


 Нажато {count} раз


)
}

<Прилавок />

## Внешние компоненты
импортировать счетчики из '../components/counters'

<Счетчики />

Этот файл Markdown содержит определение компонента счетчика. После этого он импортирует компонент Counters из компоненты каталог.

Если вы собираетесь использовать один и тот же компонент на своем сайте документации, лучше всего создать его как отдельный компонент и импортировать, когда он вам понадобится.

Узнайте больше об уценке

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