# Введение

VuePress состоит из двух частей: минималистичный генератор статических сайтов с системой пользовательских тем, основанной на Vue, и тема по умолчанию, оптимизированная для написания технической документации. Он был создан для поддержки потребностей в документировании собственных проектов экосистемы Vue.

Каждая страница, сгенерированная VuePress, имеет собственный пре-рендеренный статичный HTML, обеспечивающий великолепную скорость загрузки и дружелюбность к SEO. Однако, как только страница будет загружена, Vue использует статический контент и превращает его в полноценное одностраничное приложение (SPA). Дополнительные страницы загружаются по требованию, по мере навигации пользователя по сайту.

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

Сайт на VuePress в действительности является SPA, работающим на Vue, Vue Router и webpack. Если вы уже использовали Vue, вы заметите аналогичный опыт разработки при написании страниц или разработке пользовательских тем (вы даже можете использовать Vue DevTools для отладки своей пользовательской темы!).

Во время сборки мы создаём серверную версию приложения и рендерим соответствующий HTML, виртуально открывая каждый маршрут. Этот подход вдохновлён командой nuxt generate фреймворка Nuxt и другими проектами, такими как Gatsby.

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

# Возможности

• Встроенные расширения markdown оптимизированные для технической документации
• Возможность использовать Vue внутри файлов markdown
• Система пользовательских тем, основанная на Vue
• Автоматическая генерация Service Worker
• Интеграция Google Analytics
• "Последнее обновление" на основе Git
• Поддержка интернационализации
• Стандартная тема:
  • Адаптивный шаблон
  • Опциональная главная страница
  • Простой поиск по заголовкам страниц из коробки
  • Поиск Algolia
  • Настраиваемая панель навигации и боковая панель
  • Авто-генерируемые ссылки на GitHub и на редактирование страницы

# В планах

VuePress всё ещё в разработке. Есть несколько вещей, которые в настоящее время не поддерживаются, но их разработка в планах:

• Поддержка плагинов
• Поддержка блогов

Пулл-реквесты приветствуются!

# Почему не ...?

# Nuxt

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

# Docsify / Docute

Оба являются отличными проектами, и также работают на Vue. Кроме того, они оба полностью завязаны на runtime и поэтому не дружелюбны к SEO. Если вы не заботитесь о SEO и не хотите разбираться с установкой зависимостей — это всё равно отличный выбор.

# Hexo

Hexo отлично справляется с документацией Vue — на самом деле нам, вероятно, ещё предстоит пройти долгий путь для миграции с него на нашем основном сайте. Самая большая проблема в том, что система тем очень статична и основывается на строках — мы действительно хотим использовать Vue как для шаблона так и для интерактивности. Кроме того, рендеринг Hexo файлов markdown не самый гибкий в конфигурировании.

# GitBook

Мы использовали GitBook для документаций большинства наших смежных проектов. Основная проблема с GitBook заключается в том, что скорость перезагрузки на этапе разработки невыносима длительна при большом количестве файлов. Тема по умолчанию имеет довольно ограниченную структуру навигации, а система тем, опять же, не основана на Vue. Команда GitBook больше ориентирована на превращение проекта в коммерческий продукт, а не в инструмент с открытыми исходными кодами.