add readme

README.md

@@ -1,58 +1,99 @@
-# Parcel boilerplate
+# Parcel template
+
+Этот проект был создан при помощи Parcel. Для знакомства и настройки
+дополнительных возможностей [обратись к документации](https://parceljs.org/).
+
+## Подготовка нового проекта
+
+1. Убедись что на компьютере установлена LTS-версия Node.js.
+   [Скачай и установи](https://nodejs.org/en/) её если необходимо.
+2. Склонируй этот репозиторий.
+3. Измени имя папки с `parcel-project-template` на имя своего проекта.
+4. Создай новый пустой репозиторий на GitHub.
+5. Открой проект в VSCode, запусти терминал и свяжи проект с GitHub-репозиторием
+   [по инструкции](https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories#changing-a-remote-repositorys-url).
+6. Установи зависимости проекта в терминале командой `npm install` .
+7. Запусти режим разработки, выполнив команду `npm start`.
+8. Перейди в браузере по адресу [http://localhost:1234](http://localhost:1234).
+   Эта страница будет автоматически перезагружаться после сохранения изменений в
+   файлах проекта.
 
-## Скрытые файлы
+## Файлы и папки
+
+- Все паршалы файлов стилей должны лежать в папке `src/sass` и импортироваться в
+  файлы стилей страниц. Например, для `index.html` файл стилей называется
+  `index.scss`.
+- Изображения добавляй в папку `src/images`. Сборщик оптимизирует их, но только
+  при деплое продакшн версии проекта. Все это происходит в облаке, чтобы не
+  нагружать твой компьютер, так как на слабых машинах это может занять много
+  времени.
+
+## Деплой
 
-Включите отображение скрытых файлов и папок в проводнике своей операционной системы, иначе вы не
-сможете выбрать и скопировать себе файлы настроек проекта, имена которых начинаются с точки.
+Для настройки деплоя проекта необходимо выполнить несколько дополнительных шагов
+по настройке твоего репозитория. Зайди во вкладку `Settings` и в подсекции
+`Actions` выбери выбери пункт `General`.
 
-## Зависимости
+![GitHub actions settings](./assets/actions-config-step-1.png)
 
-На компьютере должена быть установлена LTS-версия [Node.js](https://nodejs.org/en/) со всеми
-дополнительными инструментами кроме **Chocolatey** - его ставить не нужно.
+Пролистай страницу до последней секции, в которой убедись что выбраны опции как
+на следующем изображении и нажми `Save`. Без этих настроек у сборки будет
+недостаточно прав для автоматизации процесса деплоя.
 
-## Перед началом работы
+![GitHub actions settings](./assets/actions-config-step-2.png)
 
-Один раз на проект установить все зависимости.
+Продакшн версия проекта будет автоматически собираться и деплоиться на GitHub
+Pages, в ветку `gh-pages`, каждый раз когда обновляется ветка `main`. Например,
+после прямого пуша или принятого пул-реквеста. Для этого необходимо в файле
+`package.json` отредактировать поле `homepage` и скрипт `build`, заменив
+`your_username` и `your_repo_name` на свои, и отправить изменения на GitHub.
 
-```shell
-npm ci
+```json
+"homepage": "https://your_username.github.io/your_repo_name/",
+"scripts": {
+  "build": "parcel build src/*.html --public-url /your_repo_name/"
+},
 ```
 
-### Разработка
+Далее необходимо зайти в настройки GitHub-репозитория (`Settings` > `Pages`) и
+выставить раздачу продакшн версии файлов из папки `/root` ветки `gh-pages`, если
+это небыло сделано автоматически.
 
-Запустить режим разработки.
+![GitHub Pages settings](./assets/repo-settings.png)
 
-```shell
-npm run dev
-```
+### Статус деплоя
 
-Во вкладке браузера перейти по адресу [http://localhost:1234](http://localhost:1234).
+Статус деплоя крайнего коммита отображается иконкой возле его идентификатора.
 
-### Деплой
+- **Желтый цвет** - выполняется сборка и деплой проекта.
+- **Зеленый цвет** - деплой завершился успешно.
+- **Красный цвет** - во время линтинга, сборки или деплоя произошла ошибка.
 
-Сборка будет автоматически собирать и деплоить продакшен версию проекта на GitHub Pages, в ветку
-`gh-pages`, каждый раз когда обновляется ветка `main`. Например, после прямого пуша или принятого
-пул-реквеста. Для этого необходимо в файле `package.json` отредактировать поле `homepage` и скрипт
-`build`, заменив `имя_пользователя` и `имя_репозитория` на свои.
+Более детальную информацию о статусе можно посмотреть кликнув по иконке, и в
+выпадающем окне перейти по ссылке `Details`.
 
-```json
-"homepage": "https://имя_пользователя.github.io/имя_репозитория",
-"scripts": {
-  "build": "parcel build src/*.html --public-url /имя_репозитория/"
-},
-```
+![Deployment status](./assets/status.png)
 
-На всякий случай стоит зайти в настройки репозитория `Settings` > `Pages` и убедиться что продакшен
-версии файлов раздаются из папки `/root` ветки `gh-pages`.
+### Живая страница
 
-Через какое-то время живую страницу можно будет посмотреть по адресу указанному в отредактированном
-свойстве `homepage`, например
+Через какое-то время, обычно пару минут, живую страницу можно будет посмотреть
+по адресу указанному в отредактированном свойстве `homepage`. Например, вот
+ссылка на живую версию для этого репозитория
 [https://goitacademy.github.io/parcel-project-template](https://goitacademy.github.io/parcel-project-template).
 
-## Файлы и папки
+Если открывается пустая страница, убедись что во вкладке `Console` нет ошибок
+связанных с неправильными путями к CSS и JS файлам проекта (**404**). Скорее
+всего у тебя неправильное значение свойства `homepage` или скрипта `build` в
+файле `package.json`.
 
-- Все паршалы файлов стилей должны лежать в папке `src/sass` и импортироваться в
-  `src/sass/main.scss`
-- Изображения добавляйте в папку `src/images`, заранее оптимизировав их. Сборщик просто копирует
-  используемые изображения чтобы не нагружать систему оптимизацией картинок, так как на слабых
-  компьютерах это может занять много времени.
+## Как это работает
+
+![How it works](./assets/how-it-works.png)
+
+1. После каждого пуша в ветку `main` GitHub-репозитория, запускается специальный
+   скрипт (GitHub Action) из файла `.github/workflows/deploy.yml`.
+2. Все файлы репозитория копируются на сервер, где проект инициализируется и
+   проходит сборку перед деплоем.
+3. Если все шаги прошли успешно, собранная продакшн версия файлов проекта
+   отправляется в ветку `gh-pages`. В противном случае, в логе выполнения
+   скрипта будет указано в чем проблема.

package.json

@@ -4,7 +4,7 @@
   "description": "",
   "homepage": "https://goitacademy.github.io/parcel-project-template",
   "scripts": {
-    "start": "parcel src/*.html --lazy",
+    "start": "parcel src/*.html",
     "build": "parcel build src/*.html --public-url /parcel-project-template/"
   },
   "repository": {

src/index.html

@@ -8,7 +8,7 @@
     <script type="module" src="./index.js"></script>
   </head>
   <body>
-    <!-- Add partials like so for every page -->
+    <!-- ❗️❗️❗️ Add partials like so for every page -->
     <include src="./partials/example.html" />
   </body>
 </html>

src/partials/example.html

@@ -1,33 +1,36 @@
-<article class="example">
-  <h1>HTML-фрагменты</h1>
+<article class="example" id="uk">
+  <h1>HTML-partials</h1>
 
-  <!-- Путь к изображениям из HTML-фрагмента такой, как из файла index.html -->
+  <!--
+    ❗️❗️❗️ The path to images from the HTML partial
+    is the same as from the index.html file
+  -->
   <img src="images/logo.png" alt="" width="320" />
+
   <p>
-    Плагин
+    The
     <a
       href="https://github.com/posthtml/posthtml-include"
       target="_blank"
       rel="noopener noreferrer"
     >
       posthtml-include
     </a>
-    позволяет добавлять в HTML-файлы страниц код из других HTML-файлов
-    (фрагментов). Фрагменты хранятся в папке
-    <code>src/partials</code>. Добавление происходит при компиляции файлов
-    страниц, например <code>index.html</code>.
+    plugin allows you to add code from other HTML files (fragments) to HTML page
+    files. Fragments are stored in the <code>src/partials</code> folder. The
+    addition occurs when compiling page files, such as <code>index.html</code>.
   </p>
 
   <p>
-    Этот файл <code>example.html</code> &mdash; пример такого фрагмента, с
-    разметкой определённой части главной страницы. Это очень удобно при
-    командной разработке на студенческих проектах, когда в одном HTML-файле
-    пишет несколько человек сразу.
+    This <code>example.html</code> file is an example of such a snippet, with
+    the markup of a certain part of the main page. This is very convenient for
+    team development on student projects, when several people write in one HTML
+    file at once.
   </p>
 
   <p>
-    Синтаксис добавление фрагмента в главный файл:
-    <code> &lt;include src="./partials/имя-файла.html" /&gt;</code>
+    The syntax for adding a fragment to the main file is:
+    <code> &lt;include src="./partials/filename.html" /&gt;</code>
   </p>
 
   <div class="background"></div>

src/sass/_example.scss

@@ -20,7 +20,8 @@
 
 .example .background {
   height: 240px;
-  // Путь к изображениям из SASS-файла всегда такой, как из папки css
+  // ❗️❗️❗️ The path to images from a SASS file
+  // is always the same as from the css folder.
   background-image: url('../images/logo.png');
   background-size: cover;
   background-position: center;