Чек-лист добавления новой статьи¶

Процесс¶

• Статья пишется в отдельной ветке. Пушить в мастер запрещено.
• Статья пишется полноценно локально с промежуточными коммитами.
• После завершения требуется создать "Запрос на слияние".
• В статье не должно быть битых ссылок. Статья с битыми ссылками будет автоматически отклонена при "Запросе на слияние".

Файлы¶

• Все статьи размещаются в подкаталоге docs.
• Статья размещается в предсказуемом и логичном месте.
• Имя файла: <ИмяСтатьиЛатиницей>.md.
• Все дополнительные файлы - изображения, файлы для скачивания итп, размещаются в каталоге <ИмяСтатьиЛатиницей>.assets.
• Пустых каталогов быть не должно. Файлы .gitkeep запрещены.

Контент¶

• Статья начинается с заголовка # Заголовок статьи. По этому заголовку формируется имя статьи на панели навигации.
• Все внутренние ссылки в статье должны быть указаны на конкретные файлы *.md.
• Все внутренние ссылки должны быть относительными - без указания полного пути и в начале не должно быть слеша /.
• Все пути в ссылках указаны с прямыми слешами /. Чтобы не путаться - слеши должны быть такими же, как и в адресной строке браузера.

Указание ссылок на статью¶

• Cтатья должна быть указана на главной странице в файле index.md

Дополнительные возможности в оформлении¶

• Для автоформирования содержания статьи следует использовать заголовки: ## Заголовок первого уровня, ### Заголовок второго уровня, #### Заголовок третьего уровня
• Поддерживаются смайлики, выделения, таблицы и прочее от классической markdown разметки

Оформление блоков кода¶

Код можно разукрашивать, если указать идентификатор языка, выводить в закладках и подсвечивать строки.

Примеры оформления блоков https://squidfunk.github.io/mkdocs-material/extensions/admonition/

• Примеры оформления блоков кода https://squidfunk.github.io/mkdocs-material/extensions/codehilite/

// Добавляет отбор в группу отбора условного оформления
//
// Параметры:
//  пУО    - ЭлементУсловногоОформленияКомпоновкиДанных  - Элемент условного оформления
//  ПутьКДаннымПоля        - Строка - путь к данным поля
//  пЗначение            - Любое - значение отбора
//  ВидСравнения        - ВидСравненияКомпоновкиДанных - вид сравнения.
//
// Возвращаемое значение:
//  ОбщийМодуль - этот модуль
Функция ДобавитьОтбор( пУО, Знач ПутьКДаннымПоля, Знач пЗначение, Знач ВидСравнения = Неопределено ) Экспорт

    Если ВидСравнения = Неопределено Тогда

        ВидСравнения = ВидСравненияКомпоновкиДанных.Равно;

    КонецЕсли;

    Отбор                = пУО.Отбор.Элементы.Добавить( Тип( "ЭлементОтбораКомпоновкиДанных" ) );
    Отбор.ВидСравнения   = ВидСравнения;
    Отбор.Использование  = Истина;
    Отбор.ЛевоеЗначение  = Новый ПолеКомпоновкиДанных( ПутьКДаннымПоля );
    Отбор.ПравоеЗначение = пЗначение;

    Возврат к2УО;

КонецФункции

// Добавляет отбор на заполнение поля в группу отбора условного оформления
//
// Параметры:
//  пУО    - ЭлементУсловногоОформленияКомпоновкиДанных  - Элемент условного оформления
//  ПутьКДаннымПоля - Строка - путь к данным поля.
//
// Возвращаемое значение:
//  ОбщийМодуль - этот модуль
Функция Отбор_Заполнено( пУО, Знач ПутьКДаннымПоля ) Экспорт

    ДобавитьОтбор( пУО, ПутьКДаннымПоля, , ВидСравненияКомпоновкиДанных.Заполнено );

    Возврат к2УО;

КонецФункции

}

// Добавляет отбор в группу отбора условного оформления
//
// Параметры:
//  пУО    - ЭлементУсловногоОформленияКомпоновкиДанных  - Элемент условного оформления
//  ПутьКДаннымЛевогоПоля - Строка - путь к данным поля
//  ПутьКДаннымПравогоПоля - Строка - путь к данным поля.
//
// Возвращаемое значение:
//  ОбщийМодуль - этот модуль
Функция Отбор_РавенствоПолей( пУО, Знач ПутьКДаннымЛевогоПоля, Знач ПутьКДаннымПравогоПоля ) Экспорт

    ДобавитьОтбор( пУО, ПутьКДаннымЛевогоПоля, Новый ПолеКомпоновкиДанных( ПутьКДаннымПравогоПоля ), ВидСравненияКомпоновкиДанных.Равно );

    Возврат к2УО;

КонецФункции

Файл .page¶

С помощью этих файлов можно задавать имя каталогу, сортировать файлы, включать/выключать скрытие для одного файла или скрывать каталог в целом. Подробнее: https://squidfunk.github.io/mkdocs-material/plugins/awesome-pages/#usage

Например, файл этого раздела означает, что раздел называется Знания, а сортировка - файл index.md, потом каталог Posts, потом Certification, а дальше в алфавитном порядке:

title: Знания
arrange:
    - index.md
    - Posts
    - Certification
    - ...

Локальный веб-сервер¶

Должен быть установлен python.

Установка/обновление библиотек¶

Запустить в корне репозитория pip_Install_update.bat или в командной строке выполнить следующий код:

pip install --upgrade mkdocs mkdocs-material pygments-bsl pymdown-extensions mkdocs-minify-plugin mkdocs-awesome-pages-plugin mkdocs-git-revision-date-localized-plugin

В конце должна появится надпись, что нас достиг саксесс.

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

В корне репозитория запускаем mkdocs_serve.bat или в командной строке, находясь в корне репозитория:

mkdocs serve

На первое предупреждение не пугаемся. Через некоторое время будет выведено сообщение, что сервер поднят по адресу http://127.0.0.1:8000/ и включено отслеживание изменений.

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

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

Когда сервер больше не нужен - достаточно закрыть окно комадной панели.