Организация проектов Markdown

Хорошая организация делает проекты Markdown проще в обслуживании, навигации и масштабировании. Управляете ли вы документацией для программного проекта, книгой или библиотекой контента — правильная структура экономит время и предотвращает проблемы.

Это руководство охватывает лучшие практики организации файлов и проектов Markdown.

Соглашения по именованию файлов

Используйте описательные имена

Называйте файлы на основе их содержимого, а не произвольных идентификаторов:

# Good
getting-started.md
api-reference.md
troubleshooting-guide.md

# Avoid
doc1.md
chapter_final_v2_FINAL.md

Строчные буквы с дефисами

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

# Good
user-authentication.md

# Avoid
User_Authentication.md

Структура папок

Проект документации

docs/
├── README.md
├── getting-started/
│   ├── installation.md
│   ├── configuration.md
│   └── quick-start.md
├── guides/
│   ├── user-guide.md
│   └── admin-guide.md
├── reference/
│   ├── api.md
│   └── cli.md
└── assets/
    └── images/

Книга или объёмный контент

book/
├── README.md
├── 01-introduction/
│   ├── chapter.md
│   └── images/
├── 02-fundamentals/
│   ├── chapter.md
│   └── images/
└── appendix/
    └── glossary.md

Лучшие практики

Одна тема на файл

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

Используйте корневой README

Создайте README.md в корне проекта, который даёт обзор и навигацию к другим документам.

Отделяйте ресурсы

Храните изображения и другие ресурсы в выделенных папках. Используйте относительные пути для ссылок на них:

![Diagram](./assets/images/architecture.png)

Индексные файлы

В крупных проектах добавляйте индексные или обзорные файлы в каждую папку:

guides/
├── README.md  # Overview of all guides
├── user-guide.md
└── admin-guide.md

Советы по контролю версий

• .gitignore — исключайте сгенерированные файлы (PDF, HTML), если вы их регенерируете
• Осмысленные коммиты — пишите чёткие сообщения коммитов для изменений документации
• Ветвление — используйте ветки для крупных обновлений документации
• Pull request — рецензируйте изменения документации как код

Конвертация организованных проектов

Хорошо организованный проект делает пакетную конвертацию простой:

1. Перейдите к папке с документацией
2. Выберите файлы для конвертации
3. Используйте пакетную конвертацию для обработки всех
4. Скачайте ZIP с конвертированными файлами, сохраняющими вашу структуру

Связанные руководства

• Рабочий процесс Markdown для технических писателей — полный рабочий процесс
• Пакетная конвертация файлов Markdown — обработка нескольких файлов
• Markdown для документации ПО — лучшие практики для документации разработчиков