Skip to content

README.md

Latest commit

 

History

History
188 lines (135 loc) · 8.6 KB

README.md

File metadata and controls

188 lines (135 loc) · 8.6 KB
Raw

ByteCode

Двуязычный статический каталог байткодов на VitePress. Байткоды — это короткие проверенные решения для разработчиков. Контент хранится в Markdown, поиск и фильтры работают в браузере, а публикация выполняется через GitHub Pages без backend и базы данных.

Возможности

  • русский интерфейс по умолчанию и английский раздел /en/;
  • полнотекстовый поиск VitePress по страницам и коду;
  • быстрый поиск на главной по названию, описанию, тегам и исходному коду;
  • фильтр по языку и одновременный выбор нескольких тегов;
  • сохранение поиска и фильтров в URL;
  • копирование кода из карточки и со страницы байткода;
  • Git/CLI-процесс создания, проверки, просмотра и удаления контента;
  • Docker Compose для локальной разработки;
  • автоматические тесты и публикация в GitHub Pages.

Требования

  • Node.js 24 или новее;
  • npm 11 или новее;
  • Docker с Compose — только если разработка ведётся в контейнере.

Локальный запуск через npm

npm ci
npm run dev

Сайт будет доступен по адресу http://localhost:5173.

Production-сборка и её локальный просмотр:

npm run build
npm run preview

Локальная разработка в Docker

docker compose up --build

Compose монтирует исходники в /workspace, хранит node_modules и npm-кеш в отдельных volumes, включает polling для корректного hot reload на Windows/macOS и публикует dev-сервер только на 127.0.0.1.

Изменить внешний порт можно переменной окружения:

APP_PORT=4173 docker compose up --build

Остановить окружение:

docker compose down

Безопасность dev-сервера

Стабильный VitePress 1.6.4 пока использует Vite 5 и может показывать в npm audit две moderate- и одну high-уязвимость dev-сервера без доступного совместимого исправления. Production-результат — статические файлы, а локальные команды и Docker по умолчанию доступны только с этого компьютера. Не публикуйте порт 5173 во внешнюю сеть и обновите VitePress, когда исправление появится в стабильной ветке.

Структура контента

docs/
├── snippets/<language>/<slug>.md       # русский
└── en/snippets/<language>/<slug>.md    # английский

Каталог имеет один иерархический уровень — язык или технология. Дополнительные измерения задаются плоскими тегами. Это позволяет одному байткоду одновременно принадлежать, например, javascript, arrays и performance без дублирования в дереве категорий.

Рекомендуемая максимальная глубина при будущем добавлении категорий — два уровня, например backend/php. Текущий loader рекурсивно видит Markdown-файлы, но валидатор намеренно закрепляет язык первым уровнем.

Frontmatter

---
title: "Уникальные значения массива"
description: "Удаление повторов с сохранением порядка."
slug: "unique-array-values"
locale: "ru"
language: "javascript"
tags:
  - "javascript"
  - "arrays"
  - "collections"
created: "2026-08-20T14:35:12+03:00"
---

Требования:

  • slug — уникальный внутри локали и записывается в kebab-case;
  • locale — ru или en;
  • language совпадает с каталогом первого уровня;
  • tags содержит хотя бы один нормализованный тег и поддерживает несколько значений;
  • created обязателен и содержит дату и время создания в ISO 8601 с часовым поясом;
  • дата и время обновления автоматически берутся из последнего Git-коммита файла, а до первого коммита — из created;
  • страница содержит хотя бы один fenced code block;
  • русская и английская версии используют одинаковый slug.

Управление байткодами

Интерактивное создание:

npm run snippet:new

Создание с параметрами:

npm run snippet:new -- \
  --locale ru \
  --slug array-chunks \
  --language typescript \
  --tags "typescript,arrays" \
  --title "Разбить массив на части" \
  --description "Разделение массива на блоки" \
  --code-file ./snippet.ts \
  --code-language ts

CLI нормализует теги, не перезаписывает существующие файлы и автоматически выбирает достаточно длинный Markdown fence, если код содержит обратные кавычки.

Просмотр, проверка и удаление:

npm run snippets:list
npm run snippets:list -- --locale en
npm run snippets:validate
npm run snippet:remove -- --locale ru --slug array-chunks

Удаление запрашивает подтверждение. Для автоматизации можно передать --yes.

Локализация

Навигация, поиск, состояния каталога и страницы ошибок локализованы в docs/.vitepress/config.ts и Vue-компонентах темы. Контент переводится отдельными Markdown-файлами:

  • /snippets/... — русская версия;
  • /en/snippets/... — английская версия.

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

Проверки

npm test
npm run typecheck
npm run snippets:validate
npm run build

Тесты покрывают fuzzy-поиск, кириллицу, мультитеги, изоляцию локалей, схему frontmatter, дубли slug, соответствие путей, безопасное создание и удаление файлов.

GitHub Pages

Workflow находится в .github/workflows/deploy.yml и при push в main или master выполняет:

  1. npm ci;
  2. тесты и typecheck;
  3. production-сборку VitePress;
  4. публикацию docs/.vitepress/dist в GitHub Pages.

В настройках репозитория откройте Settings → Pages и выберите GitHub Actions в качестве источника публикации.

VitePress автоматически определяет базовый путь:

  • / для репозитория <owner>.github.io;
  • /<repository>/ для обычного project site.

Локально базовый путь можно проверить явно:

BASE_PATH=/bytecode/ npm run build

Основные каталоги

docs/.vitepress/theme/   # Vue-компоненты, поиск и оформление
docs/snippets/           # русские байткоды
docs/en/snippets/        # английские байткоды
scripts/                 # Git/CLI-инструменты
tests/                   # Vitest