Как установить Docusaurus на linux

at0mSec

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

Предварительные условия

Перед установкой Docusaurus необходимо установить следующее необходимое программное обеспечение:

  • Node.js (>=12.13.0,<13.0.0 || >=14.15.0)
  • Yarn или NPM

Node.js

Docusaurus построен на React и требует Node.js для работы.

$ node -v

Это выведет установленную версию Node. Если она меньше 12.13.0 или находится между 13.0.0 и 14.15.0, вам необходимо обновить Node.js в вашей системе.

Чтобы установить Node.js, перейдите по адресу официальный сайт Node.js и загрузите программу установки для вашей операционной системы. Следуйте подсказкам, чтобы установить Node.js.

Yarn или NPM

Docusaurus использует менеджер пакетов, например Yarn или NPM, для управления своими зависимостями. Вам необходимо установить либо Yarn, либо NPM.

Чтобы проверить, установлен ли у вас Yarn:

$ yarn --version

Если Yarn не установлен, вы можете установить его через npm:

$ npm install --global yarn

Чтобы проверить, установлен ли у вас NPM:

$ npm --version

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

После проверки необходимых условий можно переходить к установке Docusaurus.

Установка Docusaurus

Существует два основных способа установки Docusaurus — с помощью классического шаблона или с помощью одной команды. В этом разделе мы рассмотрим оба способа.

1. Использование классического шаблона

Классический шаблон представляет собой скелет проекта для быстрого начала работы с некоторыми примерами контента. Это рекомендуемый подход, если вы новичок в Docusaurus.

Чтобы установить Docusaurus с помощью классического шаблона:

  1. Создайте новый каталог для вашего сайта Docusaurus:
$ mkdir my-website
$ cd my-website
  1. Запустите скрипт установки Docusaurus с помощью npx:
$ npx @docusaurus/init@latest init --template classic

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

  1. Запустите сервер разработки Docusaurus:
$ cd my-website
$ npm start

Откроется веб-сайт по адресу http://localhost:3000/ , где вы можете начать добавлять контент.

Вот и все! Теперь Docusaurus установлен и работает на классическом шаблоне.

2. Использование одной команды

Вы также можете создать голый сайт Docusaurus с помощью одной команды npx:

$ npx @docusaurus/init@latest init

Это позволит установить Docusaurus и создать минимальную структуру проекта без каких-либо документов или примеров.

Чтобы запустить сервер разработки:

$ cd my-website
$ npm start

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

Структура проекта

После установки Docusaurus вы увидите сгенерированную структуру папок:

my-website
├── blog
├── docs
├── src
│   ├── css
│   └── pages 
├── static
├── package.json
├── sidebars.js
├── docusaurus.config.js
└── .gitignore

Вот для чего нужны все эти папки и файлы:

  • /blog — Содержит записи блога, которые будут отображаться в разделе блога.
  • /docs — Содержит файлы Markdown для документов, которые будут отображаться в разделе «Документы».
  • /src — Содержит компоненты React, CSS-файлы, статические страницы и другой исходный код.
  • /src/css — CSS-файлы для стилизации сайта.
  • /src/pages — Статические страницы, такие как главная страница, страница о сайте, страница контактов и т. д.
  • /static — Статические активы, такие как изображения, pdf-файлы и т. д., находятся здесь.
  • package.json — Зависимости и скрипты NPM для разработки.
  • sidebars.js — Конфигурация для левой боковой панели навигации.
  • docusaurus.config.js — Основной файл конфигурации сайта.
  • .gitignore — Указывает git’у, какие файлы не отслеживать.

Запуск сервера разработки

Для предварительного просмотра сайта в локальном режиме можно запустить сервер разработки Docusaurus:

$ npm start

Это запустит сервер разработки по адресу http://localhost:3000/ и перестраивайте сайт по мере внесения изменений.

Функция горячей перезагрузки будет автоматически обновлять страницу по мере редактирования файлов.

Настройка Docusaurus

Основным файлом конфигурации является docusaurus.config.js , расположенный в корне.

Этот файл содержит настройки для:

  • Метаданные сайта, такие как название, теглайн, url, favicon и т.д.
  • Навигационные ссылки в верхнем и нижнем колонтитулах.
  • Цветовая тема.
  • Пользовательские CSS и JavaScript
  • Пользовательские плагины Markdown
  • Добавление пользовательских страниц
  • Регистрация Документов, Блога, Пользовательских страниц
  • И многие другие параметры конфигурации.

Например, чтобы изменить название сайта:

// docusaurus.config.js
module.exports = {
  title: 'My Site Title',
  tagline: 'The tagline of my site',
  // ...
}

См. Документация по конфигурации Docusaurus для получения полного списка опций.

[sidebars.js используется для настройки левой боковой навигации по документам. Он позволяет указать, какие документы должны быть включены в боковую панель и в каком порядке.

Например:

// sidebars.js
module.exports = {
  tutorialSidebar: [
    'intro',
    'install',
    {
      type: 'category',
      label: 'Guides',
      items: [
        'guide1',
        'guide2'
      ]
    }
  ],
}

Это сопоставляет документ intro.md к элементу боковой панели «Введение», install.md к пункту «Установка» и так далее.

[Документация по Docusaurus содержит полный справочник по всем параметрам конфигурации.

Создание страниц

Чтобы добавить новую страницу, например «О нас», создайте JSX-файл по адресу src/pages/about.js:

// src/pages/about.js
import React from 'react';
function About() {
  return (
    <main>
      <h1>About Us</h1>
      <p>This page tells you all about us...</p>
    </main>
  )
}
export default About;

Этот компонент React будет отображаться в виде страницы на маршруте /about.

Аналогичным образом можно добавить такие страницы, как /contact, /pricing, /terms и т.д.

См. Документация по Docusaurus на страницах для получения более подробной информации.

Добавление записей в блог

Чтобы создать новую запись в блоге, добавьте файл в формате Markdown в папку blog каталог. Например:

blog/welcome.md:

---
slug: welcome
title: Welcome to my Blog
author: John Doe
author_title: Principal Author
author_url: https://github.com/john
author_image_url: https://avatars3.githubusercontent.com/u/123?s=400&v=4  
tags: [hello, docusaurus]
---
Welcome to my new blog! This is my first post.
I will write about my journey with Docusaurus and share my thoughts. Stick around for more to come!

Атрибуты поста позволяют настроить заголовок блога. Docusaurus будет читать эти файлы Markdown и генерировать красивую страницу блога для каждого поста.

Обратитесь к Документация блога Docusaurus для получения более подробной информации о создании записей в блоге.

Добавление документации

Чтобы добавить страницы документации, создайте файлы в формате Markdown внутри папки /docs папке.

Например:

docs/intro.md

# Introduction
Welcome to my documentation site!
I will cover how to install Docusaurus and discuss key concepts.

docs/install.md

# Installation
You can install Docusaurus using:
```bash
npm init docusaurus@latest
```
This will get you up and running quickly.

Файлы в формате Markdown будут преобразованы в HTML и красиво оформлены с такими функциями, как боковая панель, навигация, поиск и т. д.

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

Обратитесь к Документация по Docusaurus для получения более подробной информации о доступных функциях Markdown.

Версионирование

Docusaurus позволяет легко поддерживать версии документации с помощью функции версий.

Чтобы использовать версионность, сначала инициализируйте docs:

$ npm run docusaurus docs:version 1.0.0

Это создаст versioned_docs и скопирует существующую папку docs содержимое папки в versions/1.0.0 в подпапку.

Затем вы можете вносить изменения в документацию в папке docs , которые будут отражены в папке latest версии.

Чтобы создать новую версию:

$ npm run docusaurus docs:version 1.0.1

Это скопирует текущую docs в versions/1.0.1 в качестве моментального снимка. Вы можете переключаться между версиями, выбирая их в раскрывающемся списке версий.

См. Руководство по версионированию Docusaurus для получения более подробной информации.

Темы

Docusaurus поставляется с несколькими темами, включая:

  • Классическая — Классическая тема Docusaurus.
  • Bootstrap — Тема со стилями Bootstrap.
  • Minimal — Минимальная тема с простым CSS.

Тема может быть настроена в docusaurus.config.js:

module.exports = {
  // ...
  themeConfig: {
    navbar: {
      title: 'Site Title',
      logo: {
        alt: 'Site Logo',
        src: 'img/logo.svg',
      } 
    },
  },
  themes: ['@docusaurus/theme-classic'],
}

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

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

Развертывание

Когда ваш сайт Docusaurus готов, вы можете легко развернуть его.

Сначала создайте статические HTML-страницы:

$ npm run build

В результате будет сгенерирован файл build папку, содержащую HTML-страницы, связки JavaScript и активы.

Теперь вы можете развернуть build папку на любом статическом хостинге, например GitHub Pages, Vercel, Netlify, Azure Static Web Apps и т. д.

Например, для развертывания на страницах GitHub:

  1. Зафиксируйте build в папку gh-pages ветку на GitHub.
  2. Настройте сайт страниц GitHub так, чтобы он указывал на gh-pages ветку.

Обратитесь к Документация по развертыванию Docusaurus для руководства по развертыванию на различных платформах.

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *