Руководство преподавателю
Простое руководство для преподавателя по работе с системой документации
🟢 Зеленый — хорошо, 🔴 Красный крестик — плохо
После внесения изменений в файлы и их сохранения (коммита), GitHub автоматически запускает процесс сборки сайта.
Как проверить статус сборки:
-
Откройте репозиторий на GitHub
-
Перейдите во вкладку "Actions" (вверху страницы)
-
Проверьте последний запуск:
- ✅ Зеленая галочка = всё работает, сайт обновился успешно
- ❌ Красный крестик = что-то пошло не так, сайт не обновился
Что делать, если появился красный крестик:
Если вы видите красный крестик после внесения изменений, пожалуйста, не пытайтесь исправлять проблему самостоятельно. Это поможет избежать дополнительных сложностей.
Что сделать:
- Не вносите новые изменения — это может усугубить ситуацию
- Обратитесь за помощью:
- Свяжитесь со старостой следующего потока
- Обратитесь к технически подкованному студенту
- Опишите, что было изменено перед появлением ошибки
Технические проблемы лучше решать вместе со специалистами, чтобы быстро восстановить работу сайта.
✏️ Редактирование материалов
Что можно редактировать, а что лучше не трогать
Для удобства работы и предотвращения технических проблем, рекомендуется редактировать только содержимое материалов, а системные настройки оставлять без изменений.
✅ Можно свободно редактировать:
- Весь текст после блока с тремя дефисами (
---) - Заголовки, списки, параграфы
- Примеры кода (если они есть в тексте)
- Содержимое разделов и подразделов
⚠️ Рекомендуется не изменять:
- Блок между тремя дефисами в начале файла — это системная информация, которая нужна для правильной работы сайта
- Названия файлов — изменение может нарушить ссылки
- Структуру папок — это может повлиять на навигацию
Пример правильного файла:
---
id: lab7
title: Лабораторная работа №7
slug: /labs/computer-organization/labs-sem7/lab7
---
# Лабораторная работа №7
[Здесь начинается текст, который можно редактировать]
## Цель работы
Изучение порта JTAG UART...
[Весь остальной текст можно править свободно]
Блок с тремя дефисами (---) в начале файла — это системная информация. Если его случайно изменить или удалить, сайт может не собраться.
Пожалуйста, не изменяйте:
- Дефисы (
---) в начале и конце блока - Пробелы в строках между дефисами
- Содержимое между дефисами (строки с
id:,title:,slug:)
Если этот блок был случайно изменен — сайт не соберется и появится красный крестик в Actions.
Как редактировать через веб-интерфейс GitHub:
- Откройте нужный файл (например,
website/docs/computer-organization/labs-sem7/lab7.md) - Нажмите иконку карандаша (✏️) в правом верхнем углу
- Прокрутите вниз мимо блока с дефисами
- Редактируйте только текст ниже этого блока
- Нажмите "Commit changes" внизу страницы
Если вы не уверены, можно ли что-то изменять, лучше прокрутите страницу вниз мимо блока с дефисами и редактируйте только основной текст документа.
💾 Данные в безопасности
Материалы всегда доступны
Даже если сайт временно не работает или перестал обновляться, все методички остаются в репозитории GitHub.
Где хранятся файлы:
Все файлы с методичками находятся в папке:
website/docs/
Как скачать файл напрямую:
- Откройте нужный файл на GitHub (например,
website/docs/computer-organization/labs-sem7/lab7.md) - Нажмите кнопку "Raw" (вверху справа)
- Файл откроется в браузере как обычный текст
- Сохраните через меню браузера (Ctrl+S или Cmd+S)
Альтернативный способ:
- Откройте папку с файлами на GitHub
- Нажмите на нужный файл
- В правом верхнем углу нажмите "Download" (если доступно)
- Или скопируйте содержимое вручную
Вывод: Даже в худшем случае (сайт полностью сломался) все данные остаются доступными в репозитории GitHub. Их можно скачать, скопировать или восстановить в любой момент.
Работа с листингами кода
Автоматическое скачивание листингов
Компонент DownloadListingsButton автоматически извлекает все листинги со страницы и упаковывает их в ZIP архив. Компонент автоматически определяет наличие листингов и показывается только если они найдены на странице.
Как это работает
- Компонент ищет все заголовки
### Листинг Xна странице - Для каждого листинга находит следующий code block
- Извлекает код и определяет имя файла из заголовка или описания
- Создает ZIP архив и предлагает скачать
Автоматическое добавление
Компонент добавляется автоматически на все страницы документации через swizzle компонента DocItem/Layout. Не нужно добавлять его вручную в MD файлы!
Компонент автоматически определит наличие листингов на странице и покажется только если они найдены. Если листингов нет, кнопка не отобразится.
Важно: Компонент работает автоматически для всех страниц. Не нужно импортировать или добавлять его в markdown файлы.
Параметры компонента:
buttonText- текст на кнопке (опционально, по умолчанию: "📦 Скачать все листинги")
Формат листингов
Для корректной работы компонента листинги должны быть оформлены следующим образом:
### Листинг 8
**Исходный файл программы hex_display.s**
```assembly
// код программы
Или с именем файла в заголовке:
```markdown
### Листинг 8. Текст программы JTAG UART.s
```asm
// код программы
**Требования:**
- Заголовок должен начинаться с `### Листинг` и содержать номер
- Code block должен следовать сразу после заголовка или описания
- Язык программирования определяется автоматически из класса code block
#### Версионирование и откат изменений
**Важно:** Все изменения листингов должны быть закоммичены в git для возможности отката. Система версий основана на истории git коммитов markdown файлов.
**Откат к предыдущей версии:**
```bash
# 1. Найти нужный коммит
git log --oneline website/docs/computer-organization/labs-sem7/lab6.md
# 2. Посмотреть изменения в конкретной версии
git show <commit-hash>:website/docs/computer-organization/labs-sem7/lab6.md
# 3. Восстановить файл из конкретного коммита
git checkout <commit-hash> -- website/docs/computer-organization/labs-sem7/lab6.md
# 4. Проверить изменения и закоммитить
git add website/docs/computer-organization/labs-sem7/lab6.md
git commit -m "docs: откат листингов к версии от <дата>"
Просмотр истории изменений листингов:
# Список всех версий файла с датами
git log --format="%h %ad %s" --date=short website/docs/computer-organization/labs-sem7/lab6.md
# Просмотр изменений в конкретном коммите
git show <commit-hash> website/docs/computer-organization/labs-sem7/lab6.md
Предотвращение проблем:
- Всегда делайте отдельный коммит при изменении листингов
- Используйте понятные сообщения коммитов:
docs: обновлен листинг 8 в lab6 - Перед массовыми изменениями создайте ветку для тестирования
- Проверяйте работу компонента скачивания после изменений листингов
Технические детали
Определение имени файла:
Компонент определяет имя файла в следующем порядке приоритета:
- Из заголовка листинга (если указано, например: "Листинг 8. Текст программы JTAG UART.s")
- Из описания после заголовка (например: "Исходный файл программы hex_display.s")
- Автоматически:
listing-X.asm(где X - номер листинга, расширение по языку)
Поддерживаемые языки:
Компонент автоматически определяет расширение файла по языку code block:
asm,assembly→.sили.asmc→.ccpp,cxx→.cppvhdl→.vhdverilog→.v- И другие (по умолчанию
.txt)
📞 Что делать при проблемах
Если возникли проблемы:
- Красный крестик в Actions → обратитесь за помощью к технически подкованному студенту или старосте
- Вопросы по редактированию → обратитесь к старосте или студенту, знакомому с системой
- Нужно добавить новый файл → лучше обратиться за помощью, чтобы избежать технических проблем
Система создана для удобства работы с документацией. Если возникают технические вопросы, их лучше решать вместе со специалистами — это поможет быстрее найти решение и избежать дополнительных проблем.
📝 Краткая памятка
- ✅ Зеленая галочка = всё работает
- ❌ Красный крестик = ничего не трогать, обратиться за помощью
- ✏️ Редактировать только текст после блока с
--- - 💾 Данные всегда доступны в папке
website/docs/
Связанные материалы
- Как внести вклад — для студентов, которые хотят помочь с документацией
- Стандарты оформления документации — правила оформления материалов
- Работа с файлами — работа с листингами и ZIP архивами
Последнее обновление: 2025