@aagumin/marp-technical-theme

Светлая тема Marp для технических докладов и учебных материалов. Основной текст набирается шрифтом Inter, код набирается JetBrains Mono. Тема рассчитана на русский текст с английскими терминами и экспорт в PDF 16:9.

Быстрый старт

Установите Marp CLI и тему:

npm install --save-dev @marp-team/marp-cli @aagumin/marp-technical-theme

Создайте marp.config.mjs:

import { createRequire } from 'node:module'

const require = createRequire(import.meta.url)

export default {
  themeSet: [require.resolve('@aagumin/marp-technical-theme')],
  allowLocalFiles: true,
}

Скопируйте starter и замените демонстрационный текст:

cp node_modules/@aagumin/marp-technical-theme/examples/starter.md slides.md

Соберите PDF:

npx marp slides.md --pdf

Marp найдёт marp.config.mjs в текущем каталоге.

Опция allowLocalFiles: true нужна только для изображений презентации, если они лежат на диске. Шрифты уже встроены в опубликованный dist/technical.css: пакет не обращается к сети и не требует копировать файлы шрифтов в проект.

Для экспорта PDF и PNG установите Google Chrome, Microsoft Edge или Firefox. Используйте Markdown и изображения из доверенных источников, поскольку Marp получит доступ к локальным файлам.

Front matter

Каждая презентация начинается с настроек:

---
marp: true
theme: technical
size: 16:9
paginate: true
footer: Название доклада
---

Обложка скрывает footer и номер страницы. На остальных слайдах Marp показывает значение footer слева и номер справа.

Разработка темы

Клонируйте репозиторий и установите зависимости:

npm install

Доступные команды:

# Собрать dist/slides.pdf
npm run build -- slides.md

# Следить за изменениями и открыть preview
npm run preview -- slides.md

# Проверить тему на демонстрационной презентации
npm run showcase

# Собрать CSS с встроенными шрифтами
npm run build:theme

# Проверить файлы будущего npm-пакета
npm run pack:check

Локальные скрипты загружают тему из theme/technical.css. build:theme встраивает Inter и JetBrains Mono в dist/technical.css; исходные WOFF2 остаются ресурсами сборки и не входят в npm tarball. pack:check собирает тему и проверяет содержимое будущего пакета.

Обычный слайд

Класс не нужен:

# Как работает scheduler

Короткое объяснение процесса.

- Получает очередь задач
- Выбирает доступный worker
- Обновляет состояние

Fenced code block получает тёмный фон и подсветку синтаксиса:

```go
func main() {
    fmt.Println("ready")
}
```

Специальные макеты

cover

<!-- _class: cover -->

# Название доклада

English subtitle

Имя автора · Событие

section

<!-- _class: section -->

# Архитектура решения

От запроса до результата

columns

Два blockquote становятся колонками. Внутри работают заголовки, списки, изображения и короткие блоки кода.

<!-- _class: columns -->

# До и после

> ## До
>
> - Ручная настройка
> - Разный результат

> ## После
>
> - Один Markdown
> - Стабильный PDF

takeaway

<!-- _class: takeaway -->

# Надёжность начинается с **явного состояния**

Одна строка пояснения.

quote

<!-- _class: quote -->

# Инженерный ориентир

> Короткая цитата, которую легко прочитать с экрана.
>
> - Автор или источник

code

<!-- _class: code -->

# Название примера

```go
func dispatch(ctx context.Context) error {
    return queue.Run(ctx)
}
```

image-left и image-right

Класс задаёт акцент, а стандартная директива Marp создаёт сегментированное изображение.

<!-- _class: image-left -->

![bg left:42%](architecture.svg)

# Поток данных

Описание изображения и главный вывод.

Для правой стороны используйте image-right и ![bg right:42%](image.png).

Рабочие пределы

• До шести пунктов списка на обычном слайде.
• До 16 строк кода в code.
• До двух строк заголовка.
• До четырёх строк текста в каждой колонке помимо списка или изображения.
• Таблица до шести строк и пяти столбцов.

CSS не сокращает переполненный текст. Разделите материал на два слайда, если содержимое выходит за безопасную область.

Структура

assets/          исходные шрифты для сборки и лицензии
examples/        starter и 12-слайдовый showcase
scripts/         сборка и проверка PDF
theme/           technical.css
tests/           unit- и render-тесты
dist/            CSS с встроенными шрифтами и локальные результаты сборки

Публикация

Первую версию опубликуйте из локального терминала после входа в npm:

npm login
npm test
npm run pack:check
npm publish

После первого выпуска добавьте trusted publisher в настройках пакета на npmjs.com:

• GitHub user or organization: aagumin
• repository: marp-technical-theme
• workflow: publish.yml
• allowed action: npm publish

Следующие версии публикует GitHub Actions после отправки тега v*:

npm version patch
git push --follow-tags

Workflow использует OIDC и не требует постоянного npm-токена в GitHub Secrets.

Лицензии и происхождение стиля

Код темы распространяется по MIT License. Inter и JetBrains Mono распространяются по SIL Open Font License 1.1. Тексты лицензий находятся в assets/licenses.

Визуальный язык вдохновлён открытыми техническими презентациями: крупной типографикой, свободной сеткой и яркими разделителями. Тема не содержит логотипы или графические материалы CNCF и не связана с Cloud Native Computing Foundation.