16 лист. 2023 р.Читати 3 хв

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

У цій статті я пояснюю, як опублікувати сайт на Docusaurus у GitLab Pages за допомогою файлу конфігурації CI. Це альтернативний спосіб публікації сайту на Docusaurus у GitLab вашої компанії чи вашого власного облікового запису GitLab.

Наша мета — задеплоїти (опублікувати) сайт на Докузаурусі (Docusaurus) у GitLab Pages. Я використовую цей приклад сайту на Docusaurus із цієї статті.

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

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

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

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

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

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

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

Перейдіть за цим посиланням, щоб створити порожній репозиторій: https://gitlab.com/projects/new#blank_project
Заповніть ці поля: 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.