Подстановка контента (шаблонные переменные)

Content injections позволяют внедрять динамические значения прямо в markdown-файлы через шаблонные переменные. Это полезно для подстановки версий, URL API и других значений, которые меняются между сборками.

Встроенная переменная packageJson

Docusite автоматически читает package.json из корня проекта (там, где лежит docusite.config.ts) и добавляет его как переменную packageJson. Настраивать ничего не нужно — достаточно использовать в markdown:

Имя пакета: docusite

Версия: 0.2.0

Описание: Dead-simple documentation tool powered by VitePress

Если package.json не найден или не удалось его распарсить, переменная packageJson не добавляется.

Чтобы переопределить встроенное значение, объявите packageJson в contentInjections — пользовательская запись имеет приоритет.

Настройка

Определите переменные в конфигурации:

import { defineConfig } from 'docusite'

export default defineConfig({
  contentInjections: [
    { key: 'version', value: { major: 2, minor: 0, full: '2.0.0' } },
    { key: 'api', value: { baseUrl: 'https://api.example.com' } },
  ],
})

Использование в markdown

В любом markdown-файле используйте синтаксис или:

Текущая версия: 2.0.0

API базовый URL: 

Старшая версия: v2

После обработки docusite заменит шаблоны на значения:

Текущая версия: 2.0.0

API базовый URL: https://api.example.com

Старшая версия: v2

Разрешение путей

Docusite поддерживает точечную нотацию для вложенных объектов:

• {"major":2,"minor":0,"full":"2.0.0"} → весь объект, JSON-сериализованный (с HTML-экранированием фигурных скобок)
• 2.0.0 → "2.0.0"
• 2 → 2
• `` → "https://api.example.com"
• docusite → "my-project"
• 0.2.0 → "1.2.3"

Поддерживаемые типы значений

Значение (value) может быть любым JSON-сериализуемым типом:

• string — строка
• number — число
• boolean — логическое значение
• object — объект (с поддержкой вложенности через точечную нотацию)
• array — массив

Как это работает

Docusite внедряет Vite-плагин, который на этапе сборки и разработки ищет паттерн `` в markdown-файлах и заменяет его на соответствующее значение из конфигурации.