Skip to content

Latest commit

 

History

History
153 lines (111 loc) · 7.67 KB

index.md

File metadata and controls

153 lines (111 loc) · 7.67 KB
Raw

Демки

Демка (от слова demo) — это интерактивный пример кода. Демки помогают лучше понять, как работает код, о котором вы пишете. Это не картинка «вот как оно выглядит» и не фантазия «представьте себе зелёную кнопку» — это реальный код, который запускается прямо на странице. Что может быть понятнее?

Как работает

Каждая демка — это самостоятельная HTML-страница. Все демки лежат в папке demos рядом с вашей статьёй, каждая демка — в собственной подпапке. Весь код демки находится прямо в этом HTML-файле, а картинки и библиотеки, которые вы используете в демке, лежат рядом. Демки встраиваются на страницу с помощью <iframe>, но при желании демку можно открыть в отдельной вкладке.

Как создать демку

Предположим, у вас есть статья про то, как готовить яичницу. Текст статьи находится в файле index.md в такой структуре:

tools/
  eggs-cooking/
    index.md

И вы хотите сделать демку, которая показывает, как разбивать яйца. Хорошим названием демки будет описательное «Как разбивать яйца» и простой псевдоним, например, cracking. Создайте папку demos, а в ней папку cracking и положите туда HTML-файл index.html с вашей демкой:

tools/
  eggs-cooking/
    demos/
      cracking/
        index.html
    index.md

Внутри файла используйте следующий шаблон:

<!DOCTYPE html>
<html lang="ru">
<head>
  <title>DEMO — ARTICLE — Дока</title>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link rel="preconnect" href="https://fonts.googleapis.com">
  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Roboto&display=swap">
  <style>
    /* STYLES */
  </style>
</head>
<body>
  <!-- MARKUP -->
</body>
</html>

Соберите заголовок из названия демки, названия статьи и слова «Дока» в конце:

<title>Как разбивать яйца — Как готовить яичницу — Дока</title>

Стили и скрипты пишите тут же, не нужно ничего прятать по внешним файлам, сделайте демку простой и наглядной. Не забудьте использовать семейство Roboto, если в вашей демке есть текст:

<style>
  body {
    font-family: Roboto, sans-serif;
  }
</style>
<script>
  document.documentElement.className.replace('no-js', 'js')
</script>

Как добавить в демку картинку

Положите картинку рядом с демкой в папку images:

cracking/
  images/
    egg.png
  index.html

Подключите её в демке относительным путём и не забудьте прописать полезный alt:

<img src="images/egg.png" alt="Яйцо">

Как быть с серией демок

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

Но если вам всё-таки нужно несколько похожих демок, поместите их в отдельные папки и продублируйте ресурсы, чтобы демки остались автономными:

cracking/
  images/
    egg.png
  index.html
frying/
  images/
    egg.png
  index.html

Как добавить в демку библиотеку

Демку важно сделать достаточно простой, чтобы лишний код не мешал понять её суть. Но если вам не обойтись без библиотеки, то скачайте её минифицированную версию и положите рядом с демкой:

cracking/
  scripts/
    cracker.js
  index.html

И подключите библиотеку в вашей демке где-нибудь перед закрывающим </body>:

  <script src="scripts/cracker.js"></script>
</body>
</html>

Как оформить демку

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

Но если вы хотите сразу придать демке эстетичный вид, воспользуйтесь нашим руководством по стилю демок.

Как вставить демку в текст

Прямо в маркдауне вашего текста вставьте <iframe>, указав относительный путь к демке и её название:

Яйцо можно разбить множеством разных способов, например, вот так:

<iframe title="Как разбивать яйца" src="demos/cracking/" height="250"></iframe>

Указывать название файла cracking/index.html не нужно, достаточно названия папки — сервер сам найдёт файл.

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

Про ссылки

Если в демке нужно использовать ссылки, отдавайте предпочтение пустым ссылкам <a href="#">. Если важно, чтобы href не был пустым, можно использовать ссылку на главную Доки <a href="https://doka.guide/">.

Про внешние ссылки

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

⚠️ Мы просим ответственно отнестись к выбору ссылок для демок. Наш проект должен оставаться доступным для читателей из всех стран и регионов, поэтому мы не размещаем ссылки на ресурсы, которые в этих странах и регионах признаны нежелательными или запрещены на законодательном уровне.