Блог
Как создать сайт с документацией

Как создать сайт с документацией

Ранее я затронул вопрос: "Зачем техписателю сайт-портфолио"

В продолжении темы предлагаю вам пошаговую инструкцию по развертыванию веб-сайта с документацией в сети Интернет. Это лишь один из возможных вариантов. Все зависит от стека и ваших умений. Удачи!

Быстрый старт

Предварительно на компьютере пользователя должна быть установлена система контроля версий Git. Как это сделать подробно описано в официальной документации ↗ (opens in a new tab).

Шаг 1. Создать репозиторий

  1. Зарегистрируйтесь на сайте Github.com ↗ (opens in a new tab), чтобы создать аккаунт. Если у вас уже имеется зарегистрированный аккаунт, то войдите в него.
  2. Создайте новый репозиторий в своем github-аккаунте.

При этом потребуется выбрать несколько пунктов:

  • Создать публичный или приватный репозиторий. – На ваше усмотрение. Для учебных целей лучше публичный.
  • Добавить файл Readme.md. – Да. Лучше сразу добавить.
  • Выбрать лицензию. – Если вы в них не разбираетесь. Пропустите это поле.
  1. Клонируйте созданный репозиторий на локальный диск своего компьютера.

Для этого:

  • запустите терминал;
  • войдите в директорию, куда будет клонироваться репозиторий;
  • выполните команду git clone <SSH>, где <SSH> – это ключ, скопированный из созданного вами репозитория (вкладка Code -> Local -> Clone -> SSH на сайте github.com).
  1. Запустите VS Code и откройте папку клонированного репозитория.
  2. В VS Code создайте Терминал.
  3. В Терминале выполните команду git status.

В ответ система выдаст сообщение:

On branch main
Your branch is up to date with 'origin/main'.

Это означает, что на локальном диске вашего компьютера создан клон удаленного репозитория. Локальное и удаленное хранилища связаны между собой основной веткой main.

Шаг 2. Readme.md и .gitignore

2.1. Описание проекта

В корневой папке вашего проекта создайте файл с названием Readme.md. Это нужно сделать только в том случае, если данный файл не был сгенерирован автоматически на предыдущем шаге.

Создать новый файл можно в VS Code или командой mkdir Readme.mdв Терминале. Если пользуйтесь Терминалом, предварительно убедитесь, что находитесь в корневой папке вашего проекта (команда pwd).

Readme.md – это стандартный Markdown-файл, в котором обычно описывают проект, его цель, планы развития и стек технологий. Конечно, информация может быть абсолютно любой. Наличие подобного описания является общепринятым стандартом в среде разработчиков.

2.2. Добавление исключений

В корневой папке вашего проекта создайте файл с названием .gitignore следующего содержания:

dist/
node_modules/
out/
.DS_Store
.env
.eslintcache
.idea/
*.log
.next/
.turbo/
.vercel

2.3. Выгрузка в репозиторий

Сделайте коммит, чтобы добавить созданный файл в ваш удаленный github-репозиторий. Для этого в терминале VS Code поочередно выполните следующие команды:

git status // чтобы посмотреть список измененных файлов
git add . // чтобы добавить измененные файлы в git storage
git commit -m "build: add new file .gitignore" // чтобы создать коммит
git push // чтобы загрузить коммит в удаленный github-репозиторий

Данную операцию можно было бы выполнить позже. Но, на этом этапе она послужит дополнительной защитой от человеческой забывчивости.

Шаг 3. Установка Nextra 3.x

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

Алгоритм действий подробно описан на сайте Nextra в разделе Start as a New Project ↗ (opens in a new tab) 3.1. Установите Next.js, React, Nextra и Nextra Docs Theme командой:

npm i next react react-dom nextra nextra-theme-docs

3.2. Добавьте содержимое в файл package.json:

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
},

3.3. В корневой папке проекта создайте файл next.config.mjs следующего содержания:

import nextra from 'nextra'
 
const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})
 
export default withNextra()
 
// If you have other Next.js configurations, you can pass them as the parameter:
// export default withNextra({ /* other next.js config */ })

3.4. В корневой папке проекта создайте файл theme.config,jsx:

export default {
  logo: <span>My Nextra Documentation</span>,
  project: {
    link: 'https://github.com/shuding/nextra'
  }
  // ... other theme options
}

3.5. В корневой папке проекта создайте новую папку pages с вложенным файлом _app.jsx:

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />
}

3.6. В Терминале выполните команду npm run dev, чтобы запустить сайт в режиме разработчика. Чтобы зайти на сам сайт, в командной строке браузера введите http://localhost:3000.

3.7. Добавьте созданные и измененные файлы в удаленный репозиторий:

git add .
git commit -m "build: install Nextra 3.x" 
git push

Шаг 4. Создание проекта на Vercel

  1. Зарегистрируйтесь на сайте Vercel.com ↗ (opens in a new tab) и (или) войдите в аккаунт.
  2. Создайте новый проект. Далее следуйте системным указаниям и подсказкам, чтобы связать ваш проект на Vercel с вашим Github-репозиторием.
  3. После выполнения всех указаний Vercel автоматически сгенерирует сайт и опубликует его в сети по адресу: https://<название вашего проекта>.vercel.app.

Обратите внимание, что по умолчанию будет добавлен SSL-протокол (https).

Шаг 5. Подключение аналитики

Все действия выполняются в личном кабинете на сайте Vercel.com ↗ (opens in a new tab) в разделе Analytics.

Шаг 6. Подключение домена

  1. Зарегистрируйте домен у провайдера. Также, возможно, потребуется докупить услугу DNS-хостинга.
  2. В личном кабинете на сайте Vercel.com ↗ (opens in a new tab) указажите домен.
  3. На стороне провайдера в личном кабинете делегируйте домен на сервера провайдера и укажите для домена новые DNS-записи (Type A и CNAME).
  4. Ожидайте обновления информации на всех взаимосвязанных серверах. Приблизительно до 3 (трех) суток.
СодержаниеЗачем техписателю сайт-портфолио