Добавляет в документацию инструкцию о подключении Baseline (#5689)

* Добавляет краткое описание * Заканчивает описание * Меняет букву * Apply suggestions from code review Co-authored-by: Egor Levchenko <[email protected]> * Изменяет заголовок * Изменяет пример * Правит ссылку * Update docs/baseline.md Co-authored-by: Egor Levchenko <[email protected]> * Испраляет текст * Update docs/baseline.md Co-authored-by: Igor Korovchenko <[email protected]> * Update docs/baseline.md Co-authored-by: Alexey Nikitchenko <[email protected]> * Update docs/baseline.md Co-authored-by: Alexey Nikitchenko <[email protected]> * Update docs/baseline.md Co-authored-by: Alexey Nikitchenko <[email protected]> * Update docs/baseline.md Co-authored-by: Alexey Nikitchenko <[email protected]> * Изменяет описание * Дополняет * Update docs/baseline.md Co-authored-by: Alena Batitskaia <[email protected]> * Update docs/baseline.md Co-authored-by: Alena Batitskaia <[email protected]> * Update docs/baseline.md Co-authored-by: Alena Batitskaia <[email protected]> * Update docs/baseline.md Co-authored-by: Alena Batitskaia <[email protected]> * Update docs/baseline.md Co-authored-by: Alena Batitskaia <[email protected]> * Update docs/baseline.md Co-authored-by: Alena Batitskaia <[email protected]> * Корректирует описание * Дополняет описание * Update docs/examples/doka.md Co-authored-by: Alexey Nikitchenko <[email protected]> * Update docs/baseline.md Co-authored-by: Alexey Nikitchenko <[email protected]> * Update docs/baseline.md Co-authored-by: Alexey Nikitchenko <[email protected]> --------- Co-authored-by: Egor Levchenko <[email protected]> Co-authored-by: Igor Korovchenko <[email protected]> Co-authored-by: Alexey Nikitchenko <[email protected]> Co-authored-by: Alena Batitskaia <[email protected]>
doka-guide · Feb 26, 2025 · 10ba81f · 10ba81f
1 parent b74e6cc
commit 10ba81f
Show file tree

Hide file tree

Showing 4 changed files with 107 additions and 7 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -29,6 +29,7 @@
 - [Чем вы можете помочь](contributing.md)
 - [Лицензии и правила](license.md)
 - [Руководство по стилю](styleguide.md)
+- [Про подключение Baseline](baseline.md)
 - [Про раздел «На практике»](practice.md)
 - [Про рубрику «На собеседовании»](interviews.md)
 - [Инструкция по проверке орфографии](speller.md)

diff --git a/docs/baseline.md b/docs/baseline.md
@@ -0,0 +1,96 @@
+# Baseline
+
+Когда вы пишете о новой возможности веб платформы, можно показать, как она работает в основных браузерах. Так читатель поймёт, готова ли фича для использования в проектах.
+
+Мы используем для этого [Baseline](https://web.dev/baseline).
+
+Вот как отображается информация о Baseline в Доке:
+
+![Пример отображения информации о Baseline](./images/baseline.png)
+
+## Как подключить Baseline к статье
+
+Чтобы добавить Baseline к статье, надо указать baseline-конфиг в заголовке. Например:
+
+```markdown
+baseline:
+  <!-- имя группы, обязательное поле -->
+  - group: <baseline-group>
+    features:
+      <!-- список названий фич -->
+      - <baseline-feature1>
+      - <baseline-feature2>
+```
+С полным перечнем полей в заголовке можно ознакомиться в [документации](examples/doka.md).
+
+Все фичи, которые поддерживает Baseline, можно найти в YML-файлах проекта [web-features](https://github.com/web-platform-dx/web-features/tree/main/features). [Документация на английском](https://github.com/web-platform-dx/web-features/tree/main/docs)
+
+## Как найти нужную конфигурацию
+
+Проект обладает удобным поиском [web-features-explorer](https://web-platform-dx.github.io/web-features-explorer/), с помощью которого легко найти нужный конфиг.
+
+Для примера, найдём конфигурацию для доки о [CSS свойстве `display`](https://doka.guide/css/display/).
+Новейшие значения этого свойства: `flex` и `grid`. Их и будем использовать:
+
+1. С помощью поиска находим [страницу свойства](https://web-platform-dx.github.io/web-features-explorer/features/flexbox/).
+1. Переходим по ссылке «[View the feature source file](https://github.com/web-platform-dx/web-features/blob/main/features/flexbox.yml)» внизу страницы.
+1. Копируем имя файла конфигурации (без расширения) и вставляем в заголовок статьи как значение поля `group`.
+1. Копируем значения свойств в списке `compat_features` и вставляем в заголовок статьи как значение поля `features`.
+
+```markdown
+baseline:
+  - group: flexbox
+    features:
+      - css.properties.display.flex
+      - css.properties.display.inline-flex
+```
+
+5. Добавляем также нужные свойства из конфига файла [`grid`](https://github.com/web-platform-dx/web-features/blob/main/features/grid.yml):
+
+```markdown
+baseline:
+  - group: grid
+    features:
+      - css.properties.display.grid
+      - css.properties.display.inline-grid
+```
+
+Итоговая конфигурация:
+
+```markdown
+baseline:
+  - group: flexbox
+    features:
+      - css.properties.display.flex
+      - css.properties.display.inline-flex
+  - group: grid
+    features:
+      - css.properties.display.grid
+      - css.properties.display.inline-grid
+```
+
+Готово!
+
+## Как проверить конфигурацию
+
+Убедиться в том, что конфигурация Baseline указана верно, поможет локальный запуск сайта. О том, как запустить Доку локально, читайте [в инструкции](https://github.com/doka-guide/platform/blob/main/docs/how-to-run.md). Если в конфигурации нет ошибок, baseline-плашка будет отображаться в конце статьи.
+
+Дополнительный способ проверки — поиск с помощью npm-пакета `web-features`:
+
+1. Установите пакет:
+```sh
+npm install web-features
+```
+2. Перейдите в каталог `node_modules/web-features`
+3. Выполните поиск по полю `group` в файле `data.json`
+4. Если группа указана верно, она будет соответствовать объекту c полями:
+```js
+{
+  "compat_features": ..,
+  "description": ..,
+  "group": ..,
+  "name": ..,
+  "spec": ..,
+  "status": ..
+}
+```
diff --git a/docs/examples/doka.md b/docs/examples/doka.md
@@ -15,6 +15,8 @@
 ---
 title: "Название доки"
 description: "Описание для соцсетей, 160-200 символов"
+baseline:
+  - Конфигурация для отображения совместимости в популярных браузерах
 cover:
   author: nick_name
   desktop: 'images/desktop.png'
@@ -36,13 +38,14 @@ tags:
 
 <!--
 1. В description есть описание для соцсетей и поисковиков, не больше 200 символов
-2. В authors есть ники авторов основного текста
-3. В contributors перечислены ники всех соавторов и тех, кто работал над текстом (дописали «На практике»? Переписали блок? Вам сюда)
-4. В keywords записаны ключевые слова для SEO: пишем сюда слова или фразы, которых нет в тексте статьи, но по ним могут искать этот материал
-5. Удалены все пустые теги в шапке
-6. Подпапка автора есть в папке _people/_
-7. Демки лежат в подпапке _demos/_
-8. В related добавлено три ссылки на материалы, которые будут предлагаться в конце доки. Не добавляем следующий или предыдущий материал в разделе
+2. В baseline находится [конфигурация](../baseline.md) для отображения информации о совместимости в популярных браузерах
+3. В authors есть ники авторов основного текста
+4. В contributors перечислены ники всех соавторов и тех, кто работал над текстом (дописали «На практике»? Переписали блок? Вам сюда)
+5. В keywords записаны ключевые слова для SEO: пишем сюда слова или фразы, которых нет в тексте статьи, но по ним могут искать этот материал
+6. Удалены все пустые теги в шапке
+7. Подпапка автора есть в папке _people/_
+8. Демки лежат в подпапке _demos/_
+9. В related добавлено три ссылки на материалы, которые будут предлагаться в конце доки. Не добавляем следующий или предыдущий материал в разделе
 -->
 ```
 

diff --git a/docs/images/baseline.png b/docs/images/baseline.png