Перейти к основному содержимому

Работа с файлами

Этот раздел описывает работу с различными типами файлов в документации: добавление ссылок, создание ZIP архивов и работа с листингами кода.

Работа со страницей "Полезные ссылки"​

Для добавления новой ссылки в раздел links.md, не нужно верстать HTML вручную.

  1. Откройте файл website/docs/links.md.
  2. Найдите массив repositories или tools в начале файла.
  3. Добавьте новый объект в список:
{
  title: 'Название ресурса',
  description: 'Краткое описание ресурса',
  url: 'https://ссылка.на.ресурс',
  icon: '🔗' // Эмодзи-иконка
},

Карточка с ссылкой сгенерируется автоматически.

Добавление файлов для скачивания​

Если вам нужно добавить ZIP архив или другие файлы для скачивания пользователями, используйте компонент DownloadZipButton.

Создание ZIP архива​

Скрипт scripts/create-zip.js позволяет создать ZIP архив из любой папки с гибкой настройкой путей.

Базовое использование​

# Из корня проекта
node scripts/create-zip.js <исходная_папка> <выходной_файл>

Примеры:

# Упаковать папку в конкретное место
node scripts/create-zip.js "old_doc/актуальные материалы/OEVM/7/Программные заготовки" "website/static/downloads/programmnye-zagotovki.zip"

# Упаковать папку, выходной файл будет рядом с исходной папкой
node scripts/create-zip.js "old_doc/папка с файлами"

# Использовать абсолютные пути (если нужно)
node scripts/create-zip.js "D:/полный/путь/к/папке" "D:/полный/путь/к/файлу.zip"

Значения по умолчанию (для обратной совместимости)​

Если запустить скрипт без параметров, он использует значения по умолчанию:

  • Исходная папка: old_doc/актуальные материалы/OEVM/7/Программные заготовки
  • Выходной файл: website/static/downloads/programmnye-zagotovki.zip
# Без параметров (использует значения по умолчанию)
node scripts/create-zip.js

Через npm скрипт​

cd website
npm run create-zip

Важно:

  • Пути могут быть относительными (от корня проекта) или абсолютными
  • Если выходной папки не существует, она будет создана автоматически
  • Старый ZIP файл будет автоматически удален перед созданием нового
  • Скрипт работает на всех платформах (Windows, Linux, macOS, GitHub Actions)

Примечание: Перед первым использованием убедитесь, что установлен пакет archiver:

cd website
npm install --save-dev archiver

Добавление кнопки скачивания в документацию​

В MDX файле (.md) добавьте компонент DownloadZipButton:

## Исходные файлы

Для выполнения работы доступны программные заготовки:

import DownloadZipButton from '@site/src/components/DownloadZipButton';

<DownloadZipButton 
  zipPath="downloads/programmnye-zagotovki.zip" 
  buttonText="📦 Скачать программные заготовки"
/>

Параметры компонента:

  • zipPath - путь к файлу относительно website/static/ (например: "downloads/programmnye-zagotovki.zip")
  • buttonText - текст на кнопке (опционально, по умолчанию: "📦 Скачать ZIP")
  • fileName - имя файла при скачивании (опционально, по умолчанию берется из zipPath)

Важно:

  • Файлы должны быть размещены в website/static/
  • Путь указывается относительно static/, без префикса static/
  • Компонент автоматически учитывает baseUrl из конфигурации Docusaurus

Работа с листингами кода​

Автоматическое скачивание листингов​

На страницах лабораторных работ доступна функция автоматического скачивания всех листингов в ZIP архив. Компонент DownloadListingsButton автоматически определяет наличие листингов на странице и показывается только если они найдены.

Формат листингов​

Листинги должны быть оформлены следующим образом:

### Листинг 8
**Исходный файл программы hex_display.s**

```assembly
// код программы

Или с именем файла в заголовке:

```markdown
### Листинг 8. Текст программы JTAG UART.s

```asm
// код программы

**Важно:**
- Заголовок должен начинаться с `### Листинг` и содержать номер (например, `### Листинг 8`)
- После заголовка может быть описание с именем файла (опционально)
- Code block должен следовать сразу после заголовка или описания
- Язык программирования определяется автоматически из класса code block (например, `language-asm`, `language-assembly`)

#### Имена файлов в архиве

Имена файлов определяются в следующем порядке приоритета:
1. Из заголовка листинга, если указано (например, "Листинг 8. Текст программы JTAG UART.s" → `JTAG UART.s`)
2. Из описания после заголовка (например, "**Исходный файл программы hex_display.s**" → `hex_display.s`)
3. Автоматически: `listing-X.asm` (где X - номер листинга, расширение определяется по языку)

#### Автоматическое добавление

**Компонент добавляется автоматически на все страницы документации** через swizzle компонента `DocItem/Layout`. Не нужно добавлять его вручную в MD файлы!

Компонент автоматически определит наличие листингов на странице и покажется только если они найдены. Если листингов нет, кнопка не отобразится.

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

#### Версионирование листингов

Все изменения листингов сохраняются в истории git. Для просмотра предыдущих версий:

```bash
# Список версий файла
git log --oneline website/docs/computer-organization/labs-sem7/lab6.md

# Просмотр конкретной версии
git show <commit-hash>:website/docs/computer-organization/labs-sem7/lab6.md

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

git commit -m "docs: обновлен листинг 8 в lab6"

Связанные материалы​