Публикация статей в JS Camp

Для создания статей в JS Camp нужно выполнить несколько простых шагов.

Если Вы не создаёте статьи, а желаете исправить ошибку или недочет, то вы можете отредактировать любую статью в пару нажатий, как это сделать показано здесь. Но для начала нужно создать аккаунт GitHub, если не создан, и подключиться к проекту. Как это осуществить показано ниже, в Шаге 00 и Шаге 01.

Регистрация на GitHub

Для работы над общим проектом нужно создать аккаунт на сайте GitHub. Это сервис хостинга открытых IT-проектов позволяющий удобно создавать и редактировать нескольким программистам их общий проект.

Подключение к проекту

После регистрации, перейдите к библиотеке нашего проекта (jscamp.app) и нажмите кнопку Fork в правом верхнем углу экрана.

Этим самым в своем профиле Вы создаете копию библиотеки подключаемого проекта.

Скачивание проекта на свой компьютер

Есть много способов скачать проект на свой компьютер, воспользуемся популярной программой для работы с репозиториями GitKraken. Скачиваем и устанавливаем. При первом запуске программа предложит войти различными способами, предлагаем пункт Sign in with GitHub, для синхронизации GitKraken с аккаунтом GitHub.

В открывшемся окне браузера выбираем кнопку Continue authorization, для продолжения авторизации.

Для завершения регистрации потребуется подтвердить синхронизацию аккаунтов.

Таким образом, Вы связали аккаунт GitHub с GitKraken.

Для работы над общим проектом необходимо его скачать. Нажимаем сочетание клавиш Ctrl + N, либо выбираем в главном меню пункт File->Clone Repo.

В открывшемся окне выбираем раздел GitHub.com. В поле Where to clone to выбираем путь где будет находится проект на Вашем компьютере, а в поле Repository to clone выбираем имя проекта находящегося на GitHub, который будет скопирован и нажимаем кнопку Clone the repo!

После завершения загрузки проекта на ваш компьютер нажимаем кнопку Open Now - это откроет скачанный проект.

Так выглядит интерфейс GitKraken при открытом проекте.

Подключение к ветке проекта

Теперь, для начала работы, Вам необходимо переключиться на ветку разработки - gh-pages. Для этого, наведите мышку на пункт REMOTE и нажмите кнопку Add Remote.

Откроется меню Add Remote.

В поле GitHub Repo выберите пункт gHashTag/jscamp, а в поле Name введите любое имя для этого репозитория.

Нажмите кнопку Add Remote.

Начнется процесс загрузки репозитория.

После окончания загрузки Вам необходимо переключиться на ветку gh-pages. Для этого два раза нажмите по ветке основного репозитория gh-pages.

Таким образом вы переключитесь на ветку разработки gh-pages.

Подготовка к работе с кодом

Убедитесь, что на компьютере установлен какой-либо редактор кода (рекомендуем VS Code). Скачаем и установим пакет Git. Это программа для контроля версий компилируемых программ.

После запуска установщик встретит Вас стартовым окном, нажимаем кнопку Next.

На данном шаге инсталятора оставляем все по стандарту.

Далее инсталятор предложит Вам выбрать редактор кода по умолчанию, рекомендуем выбрать Visual Studio Code.

При дальнейшей установке нажимаем Next, оставляя все чекбоксы по умолчанию (только если Вы не знаете что они означают).

Установка пакетов

Для дальнейших действий нужен установленный менеджер пакетов Chocolatey. С помощью него установим пакеты node.js и yarn. Для начала процесса установки последовательно выполним в оболочке PowerShell команды:

choco install -y nodejs.install

и

choco install yarn

При установке yarn подтвердите свой выбор буквой Y.

После завершения загрузки и установки пакетов появится сообщение об успешном выполнении операций.

Мы подготовили свой компьютер для создания и редактирования статей.

Создание статьи

Открываем проект, скопированный с GitHub на шаге Шаге 02. В оболочке GitKraken выбираем пункт меню File->Open Repo in ... или открываем папку с проектом вручную.

信息

При установленном редакторе Visual Studio Code выбираем пункт меню File -> Open Repo in Visual Studio Code.

Запустится проект в выбранном редакторе.

Далее переходим к папке docs и создаем в ней новый файл. Например, blogging00.md

备注

Созданные вами файлы должны быть с расширением *.md

Теперь сделаем "шапку" созданному документу. Для этого вставляем в начало документа данный код:

---
id: ...
title:  ...
sidebar_label: ...
---

В строке id запишем уникальный код документа. В строке title - заголовок статьи. В строке sidebar_label указываем название Вашей статьи, которое будет отображаться в левом боковом меню.

Для добавления статьи в левое боковое меню сайта, необходимо добавить её имя в файл sidebars.js. Для этого в основном каталоге открываем файл sidebars.js и добавляем новую строку, например:

['Blogging']: ['blogging-00'],

Где первое поле отвечает за название раздела в левом боковом меню, а второй параметр - это уникальный id статьи, который Вы присвоили ранее.

Теперь можно приступать к набору текста.

Создание гифок

Для того чтобы добавлять гифки, пройдите обучение в этом видео.

Запуск локального сервера

Для проверки изменений текста в статье в режиме реального времени организуем запуск локального сервера. Для этого необходимо открыть оболочку PowerShell, перейти в папку с проектом командой cd Полный путь до папки и выполнить вторую команду:

yarn install

Эта команда установит оболочку быстрого создания статей, Docasaurus. Данная оболочка устанавливается единоразово. Благодаря ей можно запустить в любой момент времени локальный сервер командой:

yarn start

Локальный сервер будет работать в браузере по адресу Localhost:3000. Окно интернет-браузера с Вашим сайтом откроется автоматически и Вы сможете просматривать статью в реальном времени.

Проверка грамматики

Перед отправкой статьи нужно убедиться что текст не содержит грамматических ошибок. Проверить свой текст можно на сайте LanguageTool.

Для выполнения проверки скопируйте текст статьи в поле для текста и нажмите кнопку Check Text. Грамматические ошибки в тексте будут подсвечены.

Теперь, нажав на подсвеченное слово, Вы можете исправить грамматическую ошибку.

Добавление авторов статьи и Patreon

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

Для добавления авторов, откройте PowerShell или Терминал (на MacOS) при помощи команды cd Полный путь папки проекта перейдите в папку ранее скачанного проекта. Далее введите данную команду:

yarn add --dev all-contributors-cli

Начнется процесс загрузки и установки пакета all-contributors. Этот пакет устанавливается единожды. Благодаря этому пакету можно добавлять людей причастных к проекту и их вклад. Для этого Вам нужно находясь в папке с проектом ввести в PowerShell команду:

yarn all-contributors add Логин_GitHub Вклад

Типы вкладов в проект описаны здесь, в столбце Emoji/Type.

Логин можно узнать в профиле GitHub

Пример:

yarn all-contributors add KoDim-React mentoring

После этого, необходимо применить изменения командой:

yarn all-contributors generate

Добавленные авторы автоматически появятся в конце файла README.md

Теперь Вам необходимо скопировать весь блок этого кода и вставить в конец своей статьи.

Таким образом Вы скопируете в свой проект всех пользователей записанных в README.md Для удаления пользователей не причастных к статье Вам необходимо удалить соответствующую ячейку <td>.

Осталось добавить в конце статьи ссылку на Patreon:

[![EnglishMoji!](/img/logo/NeuroCoder.png)](https://vk.com/neurocoder)

Статья готова для отправки!

Отправка статьи

После того как Вы набрали и сохранили текст, его нужно отправить на проверку. Проверка позволяет понять можно ли внедрять Вашу работу в основной код проекта. Для этого откроем программу GitKraken и (если проект еще не открыт) откроем заранее скачанный проект на Шаге 02 кнопкой Open a repo.

Откроется окно Вашего проекта.

Справа, в блоке Unstaged Files находятся файлы, которые Вы изменили или добавили. Для применения изменений нажимаем кнопку Stage all changes.

Далее, справа внизу, у блока Commit Message в поле Summary укажем краткий комментарий того, что было сделано и нажимаем кнопку Commit changes to ... files.

Для отправки изменений на сервер GitHub нажимаем кнопку Push.

Теперь нужно отправить запрос на объединение Вашей версии кода проекта c основным репозиторием. Для этого переходим на сайт GitHub к Вашей копии проекта и выбираем ветку gh-pages.

Нажимаем кнопку Pull request.

Далее оставляем комментарий проверяющему (Ревьюверу) и нажимаем кнопку Create pull request.

Ваш проект отправлен на проверку. Когда проверяющий убедится, что все в порядке, Ваш код будет совмещен с основным. Теперь ваша статья доступна для просмотра на любом устройстве в сети Интернет!

Редактирование статьи

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

Затем открываем необходимый файл, для редактирования.

备注

Все статьи хранятся в папке docs.

Далее нажимаем кнопку Edit this file.

Теперь можно вносить нужные изменения.

Для применения изменений нужно нажать на кнопку Commit changes. При необходимости добавляем комментарий к изменениям.

В итоге создаем Pull request, как это было показано в предыдущей теме "Создание статьи". Изменения уйдут на проверку Ревьюверу.

Базовые возможности форматирования текста Docusaurus

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

Например, способы выделения текста:

:::note
Заметка.
:::

:::tip
Подсказка.
:::

:::info
Информация.
:::

:::caution
Предупреждение!
:::

:::danger
Опасность!
:::

Вот так это будет выглядеть на сайте:

备注

Заметка.

提示

Подсказка.

信息

Информация.

警告

Предупреждение!

危险

Опасность!

Также можно давать темы таким окнам, например:

:::note Тема
Заметка.
:::

Тема

Заметка.

Чтобы выделить код, используется выражение:

'```jsx
Код
```'

(Выражение используется без кавычек)

Также можно выделять слова путем добавления ``, например:

``Пример``

Будет выглядеть как: Пример

Можно сделать так что бы любой текст можно было скопировать одной кнопкой.

'```bash
Пример
```'

(Выражение используется без кавычек)

Будет выглядеть как:

Пример

Для вставки ссылки необходимо использовать слудующий синтаксис:

[Текст при нажатии на который открывается ссылка](Ссылка на вебсайт)

Пример

Аналогично вставляются изображения.

![Имя изображения, которое будет отображаться если изображение недоступно](Путь до изображения)

Для вставки изображения с ссылкой используется объединенный синтаксис двух предыдущих команд.

[![Текс](Путь до картинки)](Ссылка)

Это только самые базовые методы форматирования текста, больше можно узнать в официальной документации Docusaurus.

Вопросы:

Какую основную функцию выполняет GitHub?

1. Форум для программистов
2. Хостинг открытых IT-проектов для совместной работы
3. Облачное хранилище файлов

Какую функцию выполняет кнопка Fork на GitHub?

1. Скачивает репозиторий
2. Делает копию репозитория в Вашем профиле
3. Даёт доступ к основному репозиторию

Какое расширение должно быть у файла статьи?

1. .doc
2. .txt
3. .md

В какой папке хранятся статьи нашего проекта?

1. docs
2. blog
3. src

Какой командой добавляются пользователи причастные к проекту?

1. yarn all-contributors add
2. yarn all-contributors generate
3. yarn all-contributors init

Что делает кнопка Pull request?

1. Отправляет запрос на объединение Вашей версии кода проекта c основным репозиторием
2. Отправляет изменения кода напрямую в основной репозиторий
3. Сохраняет копию репозитория

Что такое Docusaurus?

1. Инструмент для работы с кодом
2. Инструмент для создания интернет-документов
3. Инструмент для создания разметки

Каким из перечисленных ниже способов создается выделение текста?

1. ::note ::
2. :::note :::
3. "note"

Как вставить изображение?

1. [Текст](Путь до изображения)
2. (Текст)(Путь до изображения)
3. ![Текст](Путь до изображения)

Ссылки:

1. GitHub
2. Документация Docusaurus
3. Официальный сайт GitKraken
4. Официальный сайт Visual Studio Code
5. Сайт проверки грамматики LanguageTool

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Philipp Dvinyaninov

Dmitriy Vasilev 💵

Dmitriy K. 🏫

Resoner2005 🐛 🎨 🖋