# Руководство по редактированию учебника

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

## Оглавление

1. [Добавление материалов в русскую версию учебника и перевод материалов из английской версии](#добавление-материалов-в-русскую-версию-учебника-и-перевод-материалов-из-английской-версии)
2. [Структура учебника](#структура-учебника)
3. [Запуск учебника локально](#запуск-учебника-локально)
4. [Как внести правки в учебник?](#как-внести-правки-в-учебник)
5. [Как переводить материалы из английской версии учебника?](#как-переводить-материалы-из-английской-версии-учебника)
6. [Как добавить строку кода?](#как-добавить-строку-кода)
7. [Как добавить блок кода?](#как-добавить-блок-кода)
8. [Как добавить информационный блок?](#как-добавить-информационный-блок)
9. [Как добавить предупреждающий блок?](#как-добавить-предупреждающий-блок)
10. [Как добавить блок «Новая возможность»?](#как-добавить-блок-новая-возможность)
11. [Как добавить ссылку на другую статью из учебника?](#как-добавить-ссылку-на-другую-статью-из-учебника)
12. [Как добавить изображение в статью или задачу?](#как-добавить-изображение-в-статью-или-задачу)
13. [Как добавить клавишу в текст?](#как-добавить-клавишу-в-текст)

___

### Добавление материалов в русскую версию учебника и перевод материалов из английской версии

[Версия учебника на английском языке](https://github.com/javascript-tutorial/en.javascript.info) — исходная. Все остальные версии — это переводы.

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

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

#### **Хотите добавить новую статью в русскую версию? Дополнить какую-либо из статей новой информацией? Без проблем. Единственное условие — по возможности, отправьте перевод новых материалов и в английскую версию, если знаете язык.**

* [Структура учебника](#структура-учебника)
* [Запуск учебника локально](#запуск-учебника-локально)
* [Как внести правки в учебник?](#как-внести-правки-в-учебник)
* [Как переводить материалы из английской версии учебника?](#как-переводить-материалы-из-английской-версии-учебника)
* Перед тем, как делать какие-либо <ins>масштабные</ins> правки по типу добавления новой статьи, обязательно обсудите эту идею, открыв Issue в категории «Предложить идею по улучшению материала учебника»

<ins>Несколько деталей</ins>

* *Вы* и его производные пишите с маленькой буквы
* Всегда используйте букву `ё` ([этот npm-пакет](https://github.com/hcodes/eyo) может проверить текст и вставить её, где нужно)
* Не знаете, как перевести английский термин? [Словарь «Веб-стандартов»](https://github.com/web-standards-ru/dictionary/blob/main/dictionary.md) поможет!
* Названия компаний (Google), библиотек (Jest) и аббревиатуры (DOM) не переводятся.
* <ins>**importance: n**</ins> встречающееся в начале задач - служебное поле, перевод не требуется.

<ins>Ресурсы по переводу</ins>

Чтобы улучшить ваш перевод и, вообще, письмо, полезные статьи:

* [Берегись канцелярита!](http://www.vavilon.ru/noragal/slovo2.html)
* [Словесная алгебра](http://www.vavilon.ru/noragal/slovo4.html)
* [Поиск переводов в контексте](https://context.reverso.net/перевод/)
* [DeepL - переводчик на нейросетях](https://www.deepl.com/translator)
___

### Структура учебника

Если вы планируете внести правки в одну статью (или в одну задачу), углубленное понимание структуры учебника вам не понадобится.<br>Можете сразу переходить к делу: «[Как внести правки в учебник?](#как-внести-правки-в-учебник)»

Понимание структуры понадобится в случае, если вы хотите сделать крупные изменения: например, добавить новую статью с задачами (или добавить задачи к существующей статье).
___

Каждому разделу, статье или задаче соответствует директория.

Эта директория имеет вид `N-url`, где `N` - это номер для сортировки статей и разделов (они упорядочены), а `url` – URL-имя, по которому материал будет доступен.

**В директории <ins>[1-js](1-js)</ins> находятся все разделы из <ins>первой</ins> части учебника («Введение», «Основы JavaScript», ... ).** <br>Каждая директория в <ins>[1-js](1-js)</ins> — это раздел:

* Директория 01-getting-started => Раздел «Введение»
* Директория 02-first-steps => Раздел «Основы JavaScript»
* и так далее... (по названиям директорий можно интуитивно догадаться, что это за раздел)

В этих директориях содержатся все статьи конкретного раздела (каждой статье соответствует определенная директория): для примера возьмём раздел «Введение» (директория 01-getting-started). В разделе «Введение» **4** статьи. Вот как это выглядит в Github:

<ins>В директории 01-getting-started:</ins>

* Директория 1-intro => Статья «Введение в Javascript»
* Директория 2-manuals-specifications => Статья «Справочники и спецификации»
* Директория 3-code-editors => Статья «Редакторы кода»
* Директория 4-devtools => Статья «Консоль разработчика»
* index.md => файл, который находится в каждом разделе. В нём содержится название и описание конкретного раздела.
  
  ![](https://imgur.com/J8fgF4A.png)

Вот структура файлов в директории каждой статьи:

![](https://imgur.com/QbIHhzL.png)

**Обратите внимание:** 1) не в каждой статье есть задачи 2) не в каждой задаче есть интерактивная демонстрация

**В директории <ins>[2-ui](2-ui)</ins> находятся все разделы со статьями из <ins>второй</ins> части учебника («Документ», «Введение в события», ... ).**<br>Структура такая же, как описано выше.

**Структура <ins>третьей</ins> части учебника несколько иная.**<br>Нет директории, которая объединяет все разделы со статьями (в отличие от первой и второй части учебника). 
Все разделы третьей части учебника со статьями просто расположены в репозитории:

* Директория 3-frames-and-windows => Раздел «Фреймы и окна»
* Директория 4-binary => Раздел «Бинарные данные и файлы»
* Директория 5-network => Раздел «Сетевые запросы»
* Директория 6-data-storage => Раздел «Хранение данных в браузере»
* Директория 7-animation => Раздел «Анимация»
* Директория 8-web-components => Раздел «Веб-компоненты»
* Директория 9-regular-expressions => Раздел «Регулярные выражения»
* Директория 20-css-for-js => Раздел «CSS для JavaScript-разработчика»

**<ins>[99-archive](99-archive)</ins> — архив устаревших статей.**<br>В данной директории находятся статьи, которые по той или иной причине утратили свою актуальность. Эти статьи скрыты из оглавления сайта учебника. В репозитории английской версии учебника данного архива нет.

___

### Запуск учебника локально

Для удобства редактирования учебник можно запустить локально.

Сервер для этого находится здесь: https://github.com/javascript-tutorial/server.

В `README.md` находится инструкция по запуску сервера.

___

### Как внести правки в учебник?

<ins>**Если вы хотите отредактировать только одну статью/задачу**</ins>

1. Откройте статью, которую собираетесь редактировать. Нажмите «**Редактировать на Github**»:

   ![](https://imgur.com/sAkEbHD.png)

2. Выберите необходимый файл:

   ![](https://imgur.com/QbIHhzL.png)

   **Обратите внимание:** 1) не в каждой статье есть задачи 2) не в каждой задаче есть интерактивная демонстрация

3. Нажмите на «✏»:

   ![](https://imgur.com/dtzfg3r.png)

   После чего выберите «**Fork this repository**»:

   ![](https://imgur.com/iM1EiAV.png)

   <ins>Теперь вы создали копию учебника</ins>. Всё, что вы делаете в этой копии, никак не влияет на исходный материал учебника (пока вы не отправили ваши правки на рассмотрение).

4. Отредактируйте файл. Далее следуйте указаниям на картинке ниже (согласно нумерации):

   ![](https://imgur.com/lh4fXxk.png)

   
5. Нажмите «**Create pull request**»:

   ![](https://imgur.com/54QNimX.png)

   После чего следуйте указаниям на картинке ниже:

   ![](https://imgur.com/Lt01kHy.png)

   Вы отправили правки на рассмотрение. Теперь остаётся только внимательно следить за уведомлениями на Github. 

<ins>**Если вы хотите отредактировать сразу несколько статей/задач или добавить новую статью/задачу (перед этим обязательно создайте Issue в категории «Предложить идею по улучшению материала учебника»)**</ins>

1. Откройте репозиторий учебника. Нажмите на «**Fork**»:

   ![](https://imgur.com/VEN8lm9.png)

2. Нажмите «**Create fork**»:

   ![](https://imgur.com/yjP46p0.png)

   <ins>Теперь вы создали копию учебника</ins>. Всё, что вы изменяете/создаёте в этой копии, никак не влияет на исходный материал учебника (пока вы не отправили ваши правки на рассмотрение).

4. Выберите необходимый файл согласно [структуре учебника](#структура-учебника) (или создайте его, если добавляете новую статью/задачу). После чего нажмите на «✏»:

   ![](https://imgur.com/IYVkr4U.png)

5. Отредактируйте файл. Далее следуйте указаниям на картинке ниже (согласно нумерации):

   ![](https://imgur.com/5CFfvVx.png)

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

6. Как закончите редактировать файлы, перейдите на страницу созданной вами копии учебника. Далее следуйте указаниям на картинке ниже (согласно нумерации):

   ![](https://imgur.com/6lKMoNr.png)

7. После этого следуйте указаниям на картинке ниже:

   ![](https://imgur.com/94boTqE.png)

   Вы отправили правки на рассмотрение. Теперь остаётся только внимательно следить за увемодлениями на Github. 

#### Если вы — опытный пользователь Github, можете использовать <ins>Github Desktop</ins> или <ins>git</ins> для внесения правок. Выше описаны самые простые способы, подходящие для новичков.

___

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

Перевод не обязательно должен быть слово-в-слово. Он должен быть без ошибок и, по сути, верным, хорошо объясняющим.

Если вы видите, что переведённый текст может быть улучшен, пожалуйста, <ins>[пришлите нам свои правки](#как-внести-правки-в-учебник)</ins>.

![](https://imgur.com/ZiKy04k.png)

<ins>**Текст в коде**</ins>

- Комментарии в коде – переводить.
- Строки в примерах – можно переводить, но не обязательно.
- Названия переменных, классы, идентификаторы – не надо переводить.

Например:

```js
// Example
const text = "Hello, world";
document.querySelector('.hello').innerHTML = text;
```

✅ ХОРОШО (переведён комментарий):

```js
// Пример
const text = 'Hello, world';
document.querySelector('.hello').innerHTML = text;
```

✅ ТОЖЕ ОК (переведён комментарий и текст):

```js
// Пример
const text = 'Привет, мир';
document.querySelector('.hello').innerHTML = text;
```

<ins>**Внешние ссылки**</ins>

Если есть внешняя ссылка на MDN или Wikipedia, например https://en.wikipedia.org/wiki/JavaScript, но есть версия этой же статьи на русском, поменяйте ссылку.

Например:

```md
[JavaScript](https://en.wikipedia.org/wiki/JavaScript) is a programming language.
```

✅ ПОСЛЕ ЗАМЕНЫ (en -> ru):

```md
[JavaScript](https://ru.wikipedia.org/wiki/JavaScript) – это язык программирования.
```

Если статья на MDN переведена частично, это тоже подходит.

В случае, если у ссылки нет эквивалента на русском, оставьте её как есть.

<ins>**Соглашение по переводу (глоссарий)**</ins>

**Пожалуйста, поддерживайте глоссарий в алфавитном порядке.**

| Оригинальный термин    | Перевод                                                                        |
| :--------------------- | :----------------------------------------------------------------------------- |
| Arrow function         | Стрелочная функция                                                             |
| Backtick               | Обратная кавычка                                                              |
| Bitwise operator       | Побитовый оператор                                              |
| Breakpoint             | Точка останова     |                                              
| Character class        | Символьный класс  |
| Comparison             | Операция сравнения                                     |
| Construct              | Конструкция                                     |
| Conversion             | Конвертирование                                            |
| Functionality          | Функциональность                                                               |
| Left click/right click | Левый/правый клик? Кликните? левой кнопкой мыши        |
| More in / Details in   | Подробнее в                                                      |
| Nullish coalescing operator |  Оператор нулевого слияния  |
| Script                 | Скрипт                                                        |
| “Short-circuit” evaluation | Сокращённое вычисление
| Statement              | Инструкция                                                       |
| Summary                | Итого                                                                          |

<ins>**Ресурсы по переводу**</ins>

Чтобы улучшить ваш перевод и, вообще, письмо, полезные статьи:

* [Берегись канцелярита!](http://www.vavilon.ru/noragal/slovo2.html)
* [Словесная алгебра](http://www.vavilon.ru/noragal/slovo4.html)
* [Поиск переводов в контексте](https://context.reverso.net/перевод/)
* [DeepL - переводчик на нейросетях](https://www.deepl.com/translator)

<ins>**Несколько деталей**</ins>

* *Вы* и его производные пишите с маленькой буквы
* Всегда используйте букву `ё` ([этот npm-пакет](https://github.com/hcodes/eyo) может проверить текст и вставить её, где нужно)
* Не знаете, как перевести английский термин? [Словарь «Веб-стандартов»](https://github.com/web-standards-ru/dictionary/blob/main/dictionary.md) поможет!
* Названия компаний (Google), библиотек (Jest) и аббревиатуры (DOM) не переводятся.
* <ins>**importance: n**</ins> встречающееся в начале задач - служебное поле, перевод не требуется.

___

### Как добавить строку кода?

<code>\`// ... код ... //\`</code>

___

### Как добавить блок кода?

<ins>JavaScript:</ins>

`````js
```js
// ... код ... //
```
`````

<ins>HTML:</ins>

`````js
```html
// ... код ... //
```
`````

<ins>CSS:</ins>

`````js
```css
// ... код ... //
```
`````

Если блок кода находится внутри информационного/предупреждающего блока, нужно использовать 4 обратных кавычки <code>`</code>:

``````
````smart header="Информационный блок"

```js
// ... код ... //
```

````
``````

Чтобы добавить кнопки ![](https://imgur.com/Wqn87Rb.png) в правый верхний угол блока кода, нужно добавить <ins>**run**</ins>:

`````js
```js run
// ... код ... //
```
`````

Чтобы JS-код запускался в нестрогом режиме, нужно добавить <ins>**no-strict**</ins> (по умолчанию все блоки кода запускаются с использованием строгого режима `"use strict"`):

`````js
```js run no-strict
// ... код ... //
```
`````

Чтобы отключить [подсветку синтаксиса](https://ru.wikipedia.org/wiki/Подсветка_синтаксиса) в блоке кода, нужно добавить <ins>**no-beautify**</ins>:

`````js
```js no-beautify
// ... код ... //
```
`````

Ключевые слова <ins>**run**</ins>, <ins>**no-strict**</ins>, <ins>**no-beautify**</ins> можно комбинировать:

`````js
```js run no-strict no-beautify
// ... код ... //
```
`````

Чтобы выделить определенную часть кода, нужно поместить её в `*!*  */!*`:

```js
let year = prompt('В каком году была опубликована спецификация ECMAScript-2015?', '');

*!*
if (year == 2015) alert( 'Вы правы!' );
*/!*
```

![](https://imgur.com/RvqZMfV.png)

Также `*!*  */!*` можно использовать в одной строке:

```js
let user = {
  name: "John",
  go: function() { alert(this.name) }
}*!*;*/!*

(user.go)() // John
```

![](https://imgur.com/YNcjyUf.png)

___

### Как добавить информационный блок?

![](https://imgur.com/6qSUxIQ.png)

````
```smart header="Название информационного блока"

Текст

```
````

Если внутри информационного блока находятся блоки кода, нужно использовать 4 обратных кавычки <code>`</code>:

`````
````smart header="Название информационного блока"

```js
// ... код ... //
```

````
`````

Если в названии информационного блока находятся двойные кавычки `"`, их нужно экранировать (`\"`):

`````
````smart header="\"Название\""

Текст

````
`````

___

### Как добавить предупреждающий блок?

![](https://imgur.com/DEY0IdE.png)

````
```warn header="Название предупреждающего блока"

Текст

```
````

Если внутри предупреждающего блока находятся блоки кода, нужно использовать 4 обратных кавычки <code>`</code>:

`````
````warn header="Название предупреждающего блока"

```js
// ... код ... //
```

````
`````

Если в названии предупреждающего блока находятся двойные кавычки `"`, их нужно экранировать (`\"`):

`````
````warn header="\"Название\""

Текст

````
`````

___

### Как добавить блок «Новая возможность»?

![](https://imgur.com/RZM2ZEN.png)


```
[recent browser="new"]
```

Если нужно добавить блок «Новая возможность» со ссылкой на ресурс «[caniuse.com](https://caniuse.com)»:

```
[recent caniuse="ключевое_слово_для_поиска_на_caniuse"]
```

![](https://imgur.com/mZdSHQa.png)

___

### Как добавить ссылку на другую статью из учебника?

![](https://imgur.com/K1bPgIx.png)

<code>- (У них также нет \`super\`, но мы про это не говорили. Про это будет в главе \<info:class-inheritance\>).</code>

В `<info: ... >` указывается название, по которому статья будет доступна в учебнике. 

Это название можно найти в Github:

![](https://imgur.com/xScEKkL.png)

...Или в адресной строке браузера:

![](https://imgur.com/tQ0fbPB.png)

___

### Как добавить изображение в статью или задачу?

![](https://imgur.com/PvIevN5.png)

1. Загрузите изображение в директорию со статьёй (или в директорию с задачей)
2. Добавьте изображение в определённой части `article.md` (или `task.md`/`solution.md`, если добавляете изображение в условие/решение задачи):

   ```
   ![](название_изображения.png)
   ```

___

### Как добавить клавишу в текст?

![](https://imgur.com/a4KglZW.png)

```
Обычно при нажатии `key:Enter` введённая строка кода сразу выполняется.
```