Создание скрытого текста на страницах wiki GitHub: руководство

Быстрый ответ

Если вы хотите добавить в текст вики-страниц GitHub раздел "спойлер", к которому доступ появляется после нажатия на заголовок, воспользуйтесь следующим HTML-кодом:

<details>
  <summary>Нажмите здесь, чтобы увидеть тайну!</summary>
  <!-- Птенчик знает, чем чирикнет -->
  <p>Здесь скрывается уникальная информация, которую изначально не видать.</p>
</details>

Для просмотра содержимого кликните по тегу <summary>.

Использование элементов Details и Summary

Элементы <details> и <summary> в HTML позволяют создавать скрытый, раскрывающийся контент на вики-страницах GitHub. Применение этих HTML-тегов возможно благодаря поддержке их GitHub Flavored Markdown.

Совместимость с браузерами

Основная часть современных браузеров поддерживает работу с тегом <details>. Но пользующиеся старыми браузерами могут столкнуться с проблемами отображения. Обо всем этом стоит упомянуть в описании вики.

Подробнее об этом расскажет наш спикер на видео

Исследование других форматов кроме GFM

GitHub Wiki также поддерживает форматы AsciiDoc и RST (reStructuredText). Если вам кажется, что ограничения GFM или HTML слишком суровы, воспользуйтесь этими альтернативами.

Навык грамотного вложения тегов

Для корректного и структурированного отображения содержимого спойлеров следует аккуратно располагать элементы внутри <details>:

<details>
  <summary>Основной спойлер</summary>
  <!-- Открываем карты не сразу -->
  <p>Загадка под вуалью</p>
  <details>
    <summary>Второстепенный спойлер</summary>
    <!-- Запутываем следы -->
    <p>Загадка в рамках загадки.</p>
  </details>
</details>

Учтите, что в некоторых парсерах Markdown пробел после закрывающего тега </summary> значим для правильного визуального представления.

HTML в сочетании с Markdown в теге Summary

В содержимом тега <summary> предпочтение отдается HTML. Markdown же здесь на втором плане.

Возвращение к истокам

Используйте тег <p> для более отточенного форматирования внутри <details>, чтобы обустроить единый подход к оформлению скрытого контента.

Визуализация

В загадочных играх сундук с сокровищами (🧰) скрывает что-то тайное:

🧰: [????]

Но при помощи магического ключа (<details>) на вики-страницах GitHub можно вскрыть его содержимое:

<details>
  <summary>Открыть сундук с сокровищами!</summary>
  И вуаля! Здесь `500 золотых монет`!
</details>

После использования ключа (<summary>):

Было: 🧰: [????]
Стало: 🧰: [💰 500 золотых монет]

Таким образом, <details> действует как ключ, открывающий замок одним кликом.

Создание эффекта спойлера при помощи CSS

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

CSS-шаблон для оформления спойлера

Спойлер можно создать, подобрав следующий CSS-шаблон:

[текст, раскрывающий все тайные уголки](#spoiler)

Затем примените перечисленные стили к элементам a[href="#spoiler"] и a[href="#spoiler"]::after:

a[href="#spoiler"] {
  background-color: black;
  color: black;
  text-decoration: none;
  /* Мы исчезаем, как ниндзя в тумане */
}
a[href="#spoiler"]:hover,
a[href="#spoiler"]:focus {
  color: white;
  /* И, неожиданно, текст-ниндзя снова перед вами! */
}

Однако не забывайте, что игры с CSS легче всего реализовать на GitHub Pages или в проектах с кастомными CSS. На вики-страницах наиболее эффективным решением остается использование <details>.

Внедрение изображений

Скриншоты и диаграммы наглядно демонстрируют работу скрытого контента. Главное, помните размещать изображения внутри тега <details>, чтобы сохранить суть спойлера.

Продвинутое форматирование при помощи AsciiDoc и RST

Когда перед вами стоят сложные задачи по форматированию, AsciiDoc и RST вступают в игру. Эти форматы предлагают больший выбор возможностей, чем Markdown, и поддерживаются вики GitHub.

Рассмотрите их использование, когда:

• Нужно создать сложные таблицы или построить перекрестные ссылки.
• Вы планируете работать со сложной файловой иерархией.
• Вам важна модульность и возможность повторного использования содержимого.

Полезные материалы

1. GitHub Flavored Markdown Spec – Официальная спецификация GFM.
2. Создание и подсветка блоков кода – Детальное руководство по созданию и подсветке кода.
3. Как избежать наследования стилей в CSS – Обсуждение в сообществе Stack Overflow о том, как управлять спойлерами в Markdown с помощью CSS.
4. HTML <details> – Детальное руководство на MDN.
5. HTML <summary> – Инструкция на MDN с примерами.
6. Элементы details и summary – Практические советы и примеры для работы с этими элементами.
7. Доступные аккордеоны ARIA – Информация о создании доступных спойлеров.