Templates vs Shortcodes

When to use Template vs Shortcode for interactive scenarios

Templates vs Shortcodes

Понимание разницы между отдельным видом страницы и встроенным шорткодом важно для правильной подачи.

Визуальный слой

Эти шорткоды атомами не считаются и в разнообразие проверяющих гейтом не засчитываются:

Shortcode	Назначение	Ключевые параметры
`dropcap`	буквица на первом абзаце	`lines` (2-4), `variant` (`plain`, `accent`, `framed`)
`illustration`	SVG-иллюстрация с подписью	`src` (обяз.), `alt` (обяз.), `duration`
`claim`	метка достоверности	`type` (`fact`, `src`, `debate`), `source`
`marginalia`	врезка на полях	`kind` (`note`, `quote`, `date`), `label`
`compare`	две стороны спора	`title`, `vs`; внутри ровно два `side` с `name`
`chronicle`	хронология	`title`; внутри `event` с `date` (обяз.) и `tag`
`breather`	пауза перед важным	`note`

Основное правило

┌─────────────────────────────────────────────────────────────┐
│              ↓                                               │
│              Вставляется ВНУТРИ страницы                     │
│              (между текстом, после объяснения)               │
│                                                              │
│  Template:   template: "scenario"                            │
│              ↓                                               │
│              ВСЯ СТРАНИЦА — это scenario                     │
│              (fullscreen, immersive)                         │
└─────────────────────────────────────────────────────────────┘

Когда использовать Shortcode?

Сценарий 1: Часть учебного материала

---
title: "HTML Forms Tutorial"
template: "single"  # Обычная страница
---

# HTML Forms

Сначала теория...

## Практика

Теперь попробуй сам:


Продолжаем изучение...

Результат: Сценарий встроен в страницу между текстом.

Сценарий 2: Несколько интерактивов на странице

# Изучаем условия

## Теория

Условные операторы позволяют...


## Практика


## Задание

Результат: Страница содержит несколько интерактивных элементов.

Когда использовать Template?

Сценарий 1: Immersive опыт

---
title: "The Great Bug Hunt"
template: "scenario"  # ВСЯ СТРАНИЦА — scenario
mode: "immersive"
---

Результат:

Fullscreen scenario
Нет обычного контента
Пользователь погружён в сценарий от начала до конца

Сценарий 2: Linear Story

---
title: "Journey Through the Stack"
template: "story"  # ВСЯ СТРАНИЦА — история
mode: "immersive"
---

Результат:

Scroll-based повествование
Визуальная история
Никаких других элементов

Сценарий 3: Practice Session

---
title: "JS Loops Practice"
template: "practice"  # ВСЯ СТРАНИЦА — практика
type: "exercise"
---

Результат:

Focused practice environment
Timer, HP, Progress
Нет отвлекающих элементов

Сравнительная таблица

	Shortcode	Template
Где	Внутри контента	Вся страница
Когда	Часть урока	Весь урок
Комбинация	С текстом, quiz, etc	Изолированный опыт
Fullscreen	Нет	Да
Immersive	Опционально	Обычно да
Навигация	Обычная страница	Специальная

Проверка понимания

Доступные Templates

single (по умолчанию)

Обычная страница с контентом.

template: "single"

Когда использовать:

Учебный материал с текстом
Комбинация текста и интерактива
Стандартный концепт

immersive

Полноэкранный immersive режим.

template: "immersive"
mode: "immersive"

Когда использовать:

Визуальные объяснения
Интерактивные симуляции
Погружающий опыт без отвлечений

Особенности:

Fullscreen
Скрыта навигация
Специальные controls

scenario

Branching scenario (выбор на карточках).

template: "scenario"

Когда использовать:

Принятие решений
“Choose your own adventure”
Branching stories

Характеристики:

Card-based interface
Выборы влияют на сюжет
Multiple endings

story

Linear scroll-based story.

template: "story"

Когда использовать:

Линейное повествование
Scroll-triggered анимации
Визуальное объяснение концепции

Характеристики:

Scroll-based
Визуальные эффекты
Один путь (не branching)

practice

Focused practice session.

template: "practice"
type: "exercise"

Когда использовать:

Тренировка навыков
Упражнения с механиками (timer, hp)
Assessment

Особенности:

Timer, HP, Progress
Focused UI
Результаты и feedback

Примеры использования

Пример 1: Учебный материал с embedded сценарием

---
title: "Debugging Basics"
template: "single"
type: "material"
---

# Debugging Basics

Debugging — это процесс поиска и исправления ошибок.

## Основные техники

1. Console.log()
2. Breakpoints
3. Step-through debugging

## Попробуй сам

Теперь попробуем найти баг:


## Продвинутые техники

Далее изучим...

Когда: Сценарий — это часть урока по debugging.

Пример 2: Fullscreen branching scenario

---
title: "The Great Algorithm Quest"
template: "scenario"
mode: "immersive"
type: "exercise"
---

Содержимое: Только scenario definition (через data file или inline).

Когда: Вся страница — это одна большая branching история.

Пример 3: Visual story

---
title: "How the Internet Works"
template: "story"
mode: "immersive"
---

Содержимое: Scroll-based визуальная история.

Когда: Вся страница — линейное визуальное повествование.

Пример 4: Practice session

---
title: "Array Methods Practice"
template: "practice"
type: "exercise"
---

{{< with-timer duration="15m" >}}
{{< with-hp lives="3" >}}

{{< quiz src="arrays-quiz.yaml" >}}

{{< /with-hp >}}
{{< /with-timer >}}

Когда: Вся страница — focused практика с механиками.

Комбинирование

Можно ли комбинировать?

# ❌ НЕЛЬЗЯ
template: "scenario"  # ВСЯ страница — scenario

# В контенте:

Быстрая памятка

Выбор Template

Есть только интерактив (scenario/story/practice)?
  ├─ Да → Template
  └─ Нет → single + shortcodes

Template:
  Branching? → "scenario"
  Linear visual? → "story"
  Practice? → "practice"
  Immersive? → "immersive"
  Обычный? → "single"

Выбор Shortcode

Интерактив — ЧАСТЬ страницы?
  ├─ Да → Shortcode
  └─ Нет → Template

Shortcode:
  Branching? → {{< scenario >}}
  Quiz? → {{< quiz >}}
  Cards? → {{< flashcard >}}
  Fill blanks? → {{< fill-blank >}}

Проверка понимания

Следующие шаги

Структура вернуться к обзору структуры
Front Matter полная спецификация полей
Связи подробнее о графе знаний
Каталог атомов все атомы и их шорткоды