Учебник VuePress

# Первый проект

Это пошаговое руководство по созданию простого сайта используя тему по умолчанию VuePress.

# Рабочий процесс

После того как вы установили Node.js и VuePress

Шаги создания сайта:

  • Создание рабочего каталога и измение его.
  • Запись файлов разметки (текстовые файлы с именами, заканчивающимися на .md в соответствии с простым соглашением о форматировании называется markdown), причем домашняя страница всегда называется README.md, и сохраниться в рабочем каталоге
  • Открытие окна терминала и запуск vuepress dev в командной строке. Это создает веб-сайт из ваших исходных файлов VuePress, которые включают минимум README.md и запускают веб-сервер на вашем компьютере
  • Открытие окна браузера http://localhost:8080/, для просмотра сайта
  • Внесение изменений в свои markdown файлы или создание новых. VuePress видит, что они были созданы и автоматически генерирует новый вывод каждый раз, когда вы сохраняете файл.

# Создание каталогов

Создание основного каталога проекта можно осуществить разными способами, в том числе и проводнике Windows.

Создание нового проекта можно осуществлять в любой папке диска. На этапе изучения удобней создавать папку проекта в корневой папке диска. Например: диск D:/. Далее в корне диска D:/ создадим папку в которой будет наш первый проект с названием: first_project

Внутреннее построение структуры проекта можно осуществлять в VSCode. Нажмите File -> Open Folder и выбираем созданную папку проекта.

В открывшейся папке добавьте папки и файл с заданными именами и иерархией (// - после двойной черты указаны поясняющие комментарии для элементов):

first_project           // основная папка проекта
└─ docs                 // папка для содержимого vuepress
   ├─ .vuepress         // служебная папка
   │   └─ public        // папка для картинок, используемых на главной странице
   │       └─ hero.png  // пример картинки
   └─ README.md         // Markdown-файл из которого формируется главная страница
1
2
3
4
5
6

ПРИМЕЧАНИЕ

README.md - название файла может быть набрано как в верхнем как и нижнем регистре, т.е. README.md или readme.md

# Создание первой главной страницы

В мире программирования для простого примера принято выводить результат первой попытки запуска фразой: Hello world

Добавьте эту фразу в ранее созданный вами файл readme.md

# Hello world
1

# Переход в папку проекта на Windows

ПРИМЕЧАНИЕ

Действия выполняемые в консоли можно производить в командной строке операционной системы или в терминале VSCode. Зависит от ваших предпочтений и/или от корректности работы терминала (ошибки не корректной работы терминала встречаются к сожалению). 😦

Запускаем командную строку:

windows_cmd

Если ваш проект находиться на другом диске, то для перехода напечатайте букву диска, поставьте двоеточие:

C:\Users\user-name>d:
1

Нажав Enter получите следующее:

D:\>
1

Переходим в папку с нашим проектом, введите команду cd (chage directory - сменить директорию) и укажите путь к папке проекта находящимся на указанном диске:

windows_cmd_cd

# Запуск vuepress dev docs

ПРИМЕЧАНИЕ:

Команда запуска проекта vuepress dev docs состоит из трех команд:
vuepress - обращение к установленному пакету;
dev - создает своего рода временную копию сайта на лету. Он преобразует файлы Markdown (такие, как README.md) в HTML;
docs - указывает корневую папку проекта, в которой содержатся все элементы используемые в проекте.

README.md - это все, что вам нужно для создания минимального сайта VuePress. Давайте посмотрим на наш проект. Находясь в папке проекта запустите команду vuepress dev docs в командной строке:

D:\first_project>vuepress dev docs
1

Процесс сборки проекта выглядит подобно:

vuepress_dev_docs_process

Если все пойдет хорошо, вы увидите вывод:

success [15:29:50] Build 48bb85 finished in 8451 ms!
> VuePress dev server listening at http://localhost:8080/
1
2

ПРИМЕЧАНИЕ:

http://localhost:8080/ - цифры порта:8080 могут быть другими, в зависимости от количества свободных портов и запущенных проектов.

  • Переключитесь на браузер и перейдите по указанному у вас адресу.

Вот что вы увидите:

browser_1st

# Остановка и перезапуск сборки проекта

Для завершения работы с проектом и/или подключения новых файлов и папок необходимо останавливать и запускать сборку проекта заново.

Остановка проекта:

  • перейдите в окно командной строки или терминала (смотря где вы его запускали)
  • нажмите сочетание клавиш: Ctlr + C
  • появится вопрос: ^CTerminate batch job (Y/N)?

server_stop

  • введите y и нажмите Enter

server_stoped

Запуск проекта происходит командой: vuepress dev docs в папке проекта, как это делали ранее:

D:\first_project>vuepress dev docs
1

ПРИМЕЧАНИЕ:

Для экономии времени в командной строке стрелками вверх и вниз можно выбрать уже ранее введенные команды.

# Взгляните на специальные функции темы VuePress по умолчанию

Хотя это номинально пустая тема, вы уже можете видеть, что она имеет несколько преимуществ по сравнению с обычной пустой HTML-страницей. Она имеет привлекательный набор значений по умолчанию для шрифта, полей и т.д., и они будут одинаковыми во всех достаточно современных браузерах.

Так же вы можете заметить наличие встраиваемой кнопки поиска. Поиск осуществляется по заголовкам файлов.

# Задания

Внесите изменения в файл и ознакомьтесь как будут происходить изменения.

  1. Измените текст в документе readme.md:
# Hello vuepress!!!
1

  1. Добавьте в корневой файл три других заголовка. Перед каждым заголовком ставиться решетка #. Их может быть от 1 до 6 решеток перед заголовком. Они означают важность заголовка от 1 до 6 уровня. 1 уровень самый важный и в документе должен быть один.

  2. Добавьте описание к каждому заголовку.

  3. В браузере в строке поиска созданного файла, введите значение для поиска и посмотрите на результат.

browser_1st_titles

ПРИМЕЧАНИЕ:

Для корректной работы поиска, на этапе разработки, необходимо перезапускать сборку проекта.

  1. Для закрепления материала: попробуйте заново создать новый проект на любую тему (например хобби), который по мере изучения вы будете развивать параллельно изучению материала.

← Сборка проекта →