Создание сайта из Markdown файлов: полное руководство

gistfile1.txt

# Создание сайта из Markdown файлов: полное руководство

## Содержание
- [GitHub Pages + Jekyll](#github-pages--jekyll)
- [MkDocs](#mkdocs)
- [Docusaurus](#docusaurus)
- [Размещение на GitHub](#размещение-на-github)

## GitHub Pages + Jekyll

GitHub Pages в сочетании с Jekyll представляет собой самый простой способ создания сайта из Markdown файлов.

### Основные шаги:

1. Создайте новый репозиторий с именем `username.github.io`, где username - это ваше имя пользователя на GitHub
2. Добавьте ваши Markdown файлы в репозиторий
3. Создайте файл `_config.yml` в корне репозитория и добавьте настройки темы:

```yaml
theme: jekyll-theme-minimal
title: Название вашего сайта
description: Описание вашего сайта
```

Jekyll автоматически преобразует все Markdown файлы в HTML-страницы. Они будут доступны по адресу `username.github.io`.

## MkDocs

MkDocs - это генератор статических сайтов, специально разработанный для создания документации из Markdown файлов.

### Установка и настройка:

1. Установите MkDocs:
```bash
pip install mkdocs
```

2. Создайте новый проект:
```bash
mkdocs new my-project
cd my-project
```

3. Структура проекта:
```
my-project/
├── docs/
│   └── index.md     # Ваши Markdown файлы
└── mkdocs.yml       # Файл конфигурации
```

4. Настройте `mkdocs.yml`:
```yaml
site_name: Название вашего сайта
theme: material  # Популярная тема Material for MkDocs

nav:
  - Главная: index.md
  - О проекте: about.md
```

5. Локальный предпросмотр:
```bash
mkdocs serve
```

6. Сборка сайта:
```bash
mkdocs build
```

7. Деплой на GitHub Pages:
```bash
mkdocs gh-deploy
```

## Docusaurus

Docusaurus - мощный инструмент от Facebook для создания документационных сайтов.

### Установка и настройка:

1. Создайте новый проект:
```bash
npx @docusaurus/init@latest init my-website classic
cd my-website
```

2. Структура проекта:
```
my-website/
├── docs/
│   └── intro.md    # Ваши Markdown файлы
├── src/
├── static/
└── docusaurus.config.js
```

3. Запуск локального сервера:
```bash
npm start
```

4. Сборка сайта:
```bash
npm run build
```

5. Деплой на GitHub Pages:
```bash
GIT_USER=<GITHUB_USERNAME> npm run deploy
```

## Размещение на GitHub

### Общие шаги для всех подходов:

1. Создайте новый репозиторий на GitHub

2. Инициализируйте локальный репозиторий и загрузите код:
```bash
git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/username/repo.git
git push -u origin main
```

3. Настройка GitHub Pages:
   - Перейдите в Settings > Pages в вашем репозитории
   - Включите GitHub Pages
   - Выберите ветку (обычно main или gh-pages)
   - Укажите корневую папку (/ или /docs)

### Важные замечания:

- Для личного сайта используйте репозиторий `username.github.io`
- Для проектного сайта используйте любое имя репозитория
- Сайт будет доступен по адресу:
  - Для личного: `https://username.github.io`
  - Для проекта: `https://username.github.io/repository-name`

### Рекомендации по организации контента:

1. Создайте четкую структуру папок
2. Используйте понятные имена файлов
3. Добавьте README.md с описанием проекта
4. Регулярно делайте коммиты и пуши изменений

Эти инструменты позволяют легко создавать и поддерживать сайты на основе Markdown файлов. Выбор конкретного инструмента зависит от ваших потребностей:
- Jekyll: простые сайты и блоги
- MkDocs: техническая документация
- Docusaurus: крупные документационные порталы