Skip to content

Latest commit

 

History

History
92 lines (67 loc) · 4.31 KB

doka.md

File metadata and controls

92 lines (67 loc) · 4.31 KB
Raw

Пример доки

Дока — это справочный материал, кратко и формально описывающий некое понятие, например, свойство или тег. Как спецификация, только по-русски и понятным языком.

Мы помечаем доку тегом doka в шапке.

Структура доки примерно такова:

Шапка

Код шапки 
---
title: "Название доки"
description: "Описание для соцсетей, 160-200 символов"
cover:
  author: nick_name
  desktop: 'images/desktop.png'
  mobile: 'images/mobile.png'
  alt: 'Альтернативное описание для обложки'
authors:
  - Никнейм основного автора
contributors:
  - Никнеймы всех соавторов и контрибьюторов
editors:
  - Никнеймы всех редакторов
keywords:
  - Альтернативные теги для работы поиска
related:
  - Ссылка на материал Доки по теме
tags:
  - doka
---

<!--
1. В description есть описание для соцсетей и поисковиков, не больше 200 символов
2. В authors есть ники авторов основного текста
3. В contributors перечислены ники всех соавторов и тех, кто работал над текстом (дописали «На практике»? Переписали блок? Вам сюда)
4. В keywords записаны ключевые слова для SEO: пишем сюда слова или фразы, которых нет в тексте статьи, но по ним могут искать этот материал
5. Удалены все пустые теги в шапке
6. Подпапка автора есть в папке _people/_
7. Демки лежат в подпапке _demos/_
8. В related добавлено три ссылки на материалы, которые будут предлагаться в конце доки. Не добавляем следующий или предыдущий материал в разделе
-->

Кратко

Кратко даём основное определение.

Пример

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

<div class="element"></div>
.element {
  height: 100vh;
  background-color: #a91517;
  background-image: url("https://l.imgt.es/resource-preview-imgs/1d9806ec-7ef9-49ea-b60c-f1c9ca956b0a%2Fbaymax.crop_316x237_0%252C26.preview.png?profile=max500x190");
  background-repeat: no-repeat;
}

<iframe title="Описание того, что происходит в демке." src="demos/legend-align/" height="150"></iframe>

👆 Файл index.html с демкой кладём в папку demos, в подпапку с названием демки. Обязательно указываем высоту демки в атрибуте height. В атрибуте title пишем, что в демке происходит, что она иллюстрирует.

Как пишется

Рассказываем о синтаксисе.

Как понять

Объясняем, как лучше понять этот термин, и в чём его нюансы.

Подсказки

💡 Делимся лайфхаками, которые помогают понять те или иные нюансы.

На практике

Мнения, рецепты и советы из личной практики разработчика, часто с примерами кода или демками. Если вы просто хотите добавить подсказку или дополнительную информацию в материал — лучше добавьте её в тело статьи в соответствующий раздел.

Чтобы написать что-то в раздел «На практике», создайте в папке статьи подпапку practice, а в ней файл в формате Markdown, поименованный вашим ником.