Як опублікувати сайт на Docusaurus у GitLab Pages

Попередні вимоги

Перш ніж розпочати публікацію в GitLab Pages, раджу прочитати більше про цю послугу. Або можна відразу перейти до інструкцій нижче в тексті.

• Ви створили сайт на Docusaurus за цією інструкцією
• У вас є свій сайт на Docusaurus, який потрібно опублікувати в GitLab Pages.

Якщо хоч одна з цих умов виконана, ви готові до публікації сайту на Docusaurus в GitLab Pages.

Створення репозиторію в GitLab

Спочатку потрібно створити окремий репозиторій у GitLab, якщо у вас його ще немає.

Щоб створити репозиторій у GitLab, виконайте такі дії:

1. Перейдіть за цим посиланням, щоб створити порожній репозиторій:

   https://gitlab.com/projects/new#blank_project

2. Заповніть ці поля:

   a. Project name - будь-яка назва вашого проєкту.

   b. Project slug - ім’я цього репозиторію.

   c. Виберіть Public.

   d. Зніміть вибір з опції Initialize repository with a README.

   e. Виберіть Create project.

   

Порожній репозиторій створено.

Завантажте ваш проєкт Docusaurus на сервер

Щоб створити локальний репозиторій Git у папці з вашим проєктом Docusaurus і завантажити його до новоствореного репозиторію, виконайте такі дії:

1. Склонуйте новостворений репозиторій у командному рядку:

   git clone https://gitlab.com/ivancheban/your-test-site.git
   

   де your-test-site — це ім’я вашого репозиторію.

   

2. У командному рядку перейдіть до папки your-test-site.

   cd your-test-site
   

   

3. Змініть гілку у Git на main.

   git switch -c main
   

4. Скопіюйте файли з папки вашого існуючого проєкту Docusaurus до папки your-test-site без прихованої папки .git.

   

5. У командному рядку додайте всі скопійовані файли:

   git add --all
   

6. Укажіть, які зміни внесли для доданих файлів.

   git commit -m "add files"
   

7. Завантажте змінені файли на сервер.

   git push -u origin main
   

8. Оновіть сторінку GitLab з вашим репозиторієм у браузері, щоб побачити завантажені файли.

   

Створення власної копії проєкту

Ще один спосіб (набагато простіший) — це створити копію (fork) мого проєкту з GitLab.

Щоб створити копію мого проєкту з GitLab, виконайте такі дії:

1. Перейдіть до https://gitlab.com/ivancheban/test-site.

2. Виберіть Fork.

   

3. Заповніть поля:

   a. The project namespace - виберіть своє ім’я GitLab з розкривного списку.

   b. Project slug - уведіть ім’я репозиторію.

   c. Виберіть Fork project.

   

4. Склонуйте скопійований проєкт.

   git clone https://gitlab.com/ivancheban/my-test-site.git
   

   де my-test-site — це ім’я репозиторію скопійованого проєкту.

Створення конфігурації CI

Щоб створити файл конфігурації CI (Continuous Integration), виконайте такі дії:

1. Відкрийте свій проєкт з Docusaurus у VS Code.

   

2. Натисніть кнопку New file, щоб додати новий файл.

   

3. Уведіть ім’я та розширення файлу: .gitlab-ci.yml. Натисніть Enter.

   Файл створено.

4. Скопіюйте код нижче і вставте його всередині файлу .gitlab-ci.yml.

   image: node:latest
   
   # allow caching for faster deployment
   cache:
     paths:
       - node_modules/
       - public/
       - .cache/
   
   pages:
     stage: deploy
     script:
       - yarn install
       - yarn build:gitlab
     artifacts:
         paths:
           - public
     only:
       - main
   

5. Додайте код нижче до файлу package.json.

   "build:gitlab": "docusaurus build --out-dir public",
   

   

6. Змініть значення параметру baseUrl у файлі docusaurus.config.js на /my-test-site/, де my-test-site — це ім’я вашого репозиторію.

   

7. Укажіть, які зміни внесли до файлів, і завантажте змінені файли на сервер: commit і push.

Публікація сайту в GitLab Pages

Тепер у вас є локальний проєкт із Docusaurus (локально і на сервері) з файлом конфігурації CI. Час почати публікацію.

Щоб почати публікацію в GitLab Pages, виконайте такі дії:

1. Змініть щось у тексті документації проєкту.

2. Укажіть, які зміни внесли до файлів, і завантажте змінені файли на сервер: commit і push.

3. Перейдіть до Deployments > Pages у репозиторії GitLab repo.

   

4. Перейдіть за посиланням опублікованого сайту в GitLab Pages.

   https://ivancheban.gitlab.io/my-test-site

   

Ваш сайт опубліковано в інтернеті. Публікація (deployment) запускається автоматично, коли ви вносите зміни і завантажуєте змінені файли в репозиторій. Ви можете переглянути пайплайн для кожної публікації в розділі CI/CD > Pipelines.