🚀 Автоматическое преобразование Markdown-документации с примерами кода в реальную файловую структуру проекта

Мощный Bash-инструмент для преобразования ответов LLM (ChatGPT, Claude, DeepSeek, Gemini) с описанием структуры проектов и примерами кода в работающие файловые системы.

📑 Содержание

О проекте
Ключевые возможности
Быстрый старт
Установка
Использование
Форматы входных данных
Параметры командной строки
Примеры
Интеграция
Устранение неполадок
Документация
Contributing
Лицензия
Контакты

🎯 О проекте

MD_to_Files.sh (также известный как LLM Code Projector) решает фундаментальную задачу современной разработки: преобразование теоретических архитектурных решений и примеров кода, получаемых от AI-ассистентов, в реальную работающую файловую структуру.

Проблема

Вы получаете от ChatGPT или Claude отличную структуру проекта с примерами кода в Markdown. Что дальше? Создавать каждую папку и файл вручную? Копировать код по одному файлу?

Решение

# Один простой запуск
./MD_to_Files.sh chatgpt_response.md ./my-new-project

# И ваш проект готов!

Для кого?

👨‍💻 Разработчики — быстрое прототипирование из AI-ответов
🔧 DevOps-инженеры — автоматизация создания проектных шаблонов
📝 Технические писатели — создание рабочих примеров из документации
👨‍🏫 Преподаватели — подготовка учебных материалов с кодом
👥 Команды разработки — стандартизация инициализации проектов

✨ Ключевые возможности

🌳 Умный парсинг структуры

✅ Распознавание ASCII и Unicode деревьев каталогов
✅ Создание вложенных каталогов любой глубины
✅ Поддержка различных форматов записи структуры
✅ Автоматическое определение типов узлов (каталог/файл)

💻 Интеллектуальная работа с кодом

✅ Извлечение fenced code blocks из Markdown
✅ Автоматическое связывание кода с соответствующими файлами
✅ Поддержка 30+ языков программирования
✅ Сохранение форматирования, отступов и кодировок

🔒 Безопасность и надежность

✅ Валидация путей и предотвращение path traversal
✅ Автоматическая проверка и конвертация кодировок
✅ Атомарные операции с файлами
✅ Опциональные резервные копии при обновлении

⚙️ Гибкость настройки

✅ Режим dry-run для предварительного просмотра
✅ Интерактивный выбор из нескольких структур
✅ Пакетная обработка всех найденных структур
✅ Подробное логирование с уровнями verbose

🚀 Быстрый старт

Установка (5 секунд)

# Клонируйте репозиторий
git clone https://github.com/paulmann/1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures.git
cd 1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures

# Сделайте исполняемым
chmod +x MD_to_Files.sh

# Проверьте установку
./MD_to_Files.sh --version

Первый запуск (1 минута)

Создайте простой Markdown-файл test.md:

# Test Project

```
test-app/
├── src/
│   └── app.js
└── package.json
```

**src/app.js**
```javascript
console.log('Hello from MD_to_Files!');
```

**package.json**
```json
{
  "name": "test-app",
  "version": "1.0.0"
}
```

Запустите:

./MD_to_Files.sh test.md ./output

Результат:

✓ Created directory: output/test-app/src
✓ Created file: output/test-app/src/app.js (38 bytes)
✓ Created file: output/test-app/package.json (45 bytes)
✓ Success! 2 files created in 1 directory

📦 Установка

Метод 1: Git Clone (рекомендуется)

# Клонирование
git clone https://github.com/paulmann/1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures.git
cd 1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures

# Права на выполнение
chmod +x MD_to_Files.sh

# Создание алиаса (опционально)
echo 'alias md2files="$(pwd)/MD_to_Files.sh"' >> ~/.bashrc
source ~/.bashrc

Метод 2: Прямая загрузка

# Через curl
curl -L -o ~/bin/md2files.sh \
  https://raw.githubusercontent.com/paulmann/1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures/main/MD_to_Files.sh

chmod +x ~/bin/md2files.sh

# Через wget
wget -O ~/bin/md2files.sh \
  https://raw.githubusercontent.com/paulmann/1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures/main/MD_to_Files.sh

chmod +x ~/bin/md2files.sh

Метод 3: Глобальная установка

# Символическая ссылка в PATH
sudo ln -s $(pwd)/MD_to_Files.sh /usr/local/bin/md2files

# Проверка
which md2files
md2files --version

Системные требования

Компонент	Требование
ОС	Linux 3.2+, macOS 10.12+, Windows (WSL/Cygwin), BSD
Bash	≥ 4.0 (рекомендуется 5.0+)
RAM	512 MB (1 GB для крупных проектов)
Диск	100 MB свободного места
Утилиты	`mkdir`, `touch`, `cat`, `grep`, `sed`
Опционально	`file`, `iconv`, `git`

Проверка зависимостей

# Версия Bash
bash --version

# Проверка утилит
for cmd in mkdir touch cat grep sed file iconv; do
    command -v $cmd &>/dev/null && echo "✓ $cmd" || echo "✗ $cmd"
done

💡 Использование

Базовый синтаксис

./MD_to_Files.sh [ОПЦИИ] <input_file.md> [target_directory]

Простые примеры

# Создание в текущей директории
./MD_to_Files.sh structure.md

# Создание в указанной директории
./MD_to_Files.sh structure.md ./my-project

# Предпросмотр (dry-run)
./MD_to_Files.sh -d structure.md ./preview

# Обновление существующего проекта
./MD_to_Files.sh -U structure.md ./existing-project

# Создание с метаданными проекта
./MD_to_Files.sh -P structure.md ./professional-project

# Интерактивный выбор структуры
./MD_to_Files.sh -i multi_structures.md ./output

# Обработка всех структур в файле
./MD_to_Files.sh -a documentation.md ./batch-output

Режимы работы

Режим	Опция	Описание
Создание	(по умолчанию)	Создает новую файловую структуру
Обновление	`-U`, `--update`	Обновляет существующие файлы
Проектный	`-P`, `--project`	Создает с README и метаданными
Интерактивный	`-i`, `--ask`	Выбор из нескольких структур
Пакетный	`-a`, `--find-all`	Обработка всех структур
Dry-run	`-d`, `--dry-run`	Симуляция без изменений

Дополнительные опции

Опция	Длинная форма	Описание
`-n N`	`--tree-number N`	Обработать структуру с номером N
`-C`	`--no-code`	Создать пустые файлы без кода
`-f`	`--force`	Перезаписывать без подтверждения
`-b`	`--backup`	Создавать резервные копии
`-v`	`--verbose`	Подробный вывод
`-l FILE`	`--log FILE`	Запись в файл лога
`-h`	`--help`	Показать справку
`-V`	`--version`	Показать версию

Комбинации опций

# Безопасное обновление с бэкапами и логом
./MD_to_Files.sh -U -b -v -l update.log structure.md ./project

# Пакетная обработка в режиме проекта
./MD_to_Files.sh -a -P documentation.md ./projects

# Принудительное обновление без кода
./MD_to_Files.sh -U -f -C skeleton.md ./scaffold

# Выбор конкретной структуры (3-я по счету)
./MD_to_Files.sh -n 3 variants.md ./variant-3

📝 Форматы входных данных

Структура Markdown-документа

Рекомендуемый формат:

# Название проекта

Краткое описание.

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

```
project-name/
├── directory1/
│   ├── file1.ext
│   └── file2.ext
└── file3.ext
```

## Реализация

**directory1/file1.ext**
```language
// Код для file1
```

**directory1/file2.ext**
```language
// Код для file2
```

Форматы дерева каталогов

Unicode Box-Drawing (рекомендуется):

my-project/
├── src/
│   ├── main.js
│   ├── utils.js
│   └── lib/
│       └── helper.js
├── tests/
│   └── main.test.js
└── package.json

ASCII Tree:

my-project/
|-- src/
|   |-- main.js
|   `-- utils.js
`-- package.json

Simple Indentation:

my-project/
  src/
    main.js
    utils.js
  package.json

Блоки кода

Fenced Code Blocks с языком:

**src/app.js**
```javascript
const express = require('express');
app.listen(3000);
```

**config/database.json**
```json
{
  "host": "localhost",
  "port": 5432
}
```

Поддерживаемые языки

JavaScript, TypeScript, Python, PHP, Java, C, C++, C#, Ruby, Go, Rust, Shell, Bash, HTML, CSS, SCSS, SQL, JSON, YAML, XML, Markdown и др. (30+ языков)

Методы связывания кода с файлами

Метод 1: Жирный маркер (рекомендуется)

**src/controllers/userController.js**
```javascript
exports.getUser = (req, res) => {
    res.json({ user: 'John' });
};
```

Метод 2: Заголовок секции

## src/models/User.js

```javascript
class User {
    constructor(name) { this.name = name; }
}
```

Метод 3: Label с двоеточием

File: config/database.js

```javascript
module.exports = { host: 'localhost' };
```

Приоритет: Жирный маркер > Заголовок > Label > Комментарий в коде

🎬 Примеры

Пример 1: React-приложение

Создайте react_app.md:

# React Application

```
react-app/
├── public/
│   └── index.html
├── src/
│   ├── index.js
│   ├── App.js
│   └── components/
│       ├── Header.js
│       └── Footer.js
└── package.json
```

**src/index.js**
```javascript
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(<App />);
```

**src/App.js**
```javascript
import React from 'react';
import Header from './components/Header';
import Footer from './components/Footer';

function App() {
  return (
    <div className="App">
      <Header />
      <main><h1>Welcome to React</h1></main>
      <Footer />
    </div>
  );
}

export default App;
```

**src/components/Header.js**
```javascript
import React from 'react';

function Header() {
  return <header><h2>My React App</h2></header>;
}

export default Header;
```

**src/components/Footer.js**
```javascript
import React from 'react';

function Footer() {
  return <footer><p>&copy; 2025 My App</p></footer>;
}

export default Footer;
```

**package.json**
```json
{
  "name": "react-app",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  },
  "scripts": {
    "start": "react-scripts start",
    "build": "react-scripts build"
  }
}
```

Запустите:

./MD_to_Files.sh -P react_app.md ./my-react-app
cd my-react-app/react-app
npm install
npm start

Пример 2: Express API

Вот ваш текст с заменёнными HTML-энкодированными символами на обычные — все примеры кода и структурные элементы теперь отображаются корректно для копирования и вставки:

Express REST API

textexpress-api/
├── src/
│   ├── app.js
│   ├── routes/
│   │   └── users.js
│   ├── controllers/
│   │   └── userController.js
│   └── config/
│       └── database.js
└── package.json

src/app.js

javascriptconst express = require('express');
const userRoutes = require('./routes/users');

const app = express();
app.use(express.json());
app.use('/api/users', userRoutes);

app.listen(3000, () => {
    console.log('Server on port 3000');
});

src/routes/users.js

javascriptconst express = require('express');
const router = express.Router();
const userController = require('../controllers/userController');

router.get('/', userController.getAll);
router.get('/:id', userController.getById);

module.exports = router;

src/controllers/userController.js

javascriptexports.getAll = (req, res) => {
    res.json({ users: ['John', 'Jane'] });
};

exports.getById = (req, res) => {
    const { id } = req.params;
    res.json({ user: `User ${id}` });
};

package.json

json{
  "name": "express-api",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.0"
  }
}

Запустите:

bash./MD_to_Files.sh express_api.md ./my-api
cd my-api/express-api
npm install
node src/app.js

Пример 3: Python учебный курс

Python Course

Lesson 1

textlesson-1/
├── hello.py
└── README.md

hello.py

pythonprint("Hello, World!")

README.md

text# Lesson 1: Hello World
Первая программа на Python.

Lesson 2

textlesson-2/
├── variables.py
└── README.md

variables.py

pythonname = "Student"
age = 20
print(f"Name: {name}, Age: {age}")

README.md

text# Lesson 2: Variables
Работа с переменными в Python.

Запустите:

bash./MD_to_Files.sh -a python_course.md ./course-materials

Пример 4: Обновление существующего проекта

bash# 1. Создайте резервную копию
cp -r ./my-project ./my-project.backup

# 2. Запустите обновление с бэкапами
./MD_to_Files.sh -U -b -v improvements.md ./my-project

# 3. Проверьте изменения
diff -r ./my-project ./my-project.backup

# 4. При необходимости откатите
rm -rf ./my-project
mv ./my-project.backup ./my-project

🔗 Интеграция

Git Hooks

Pre-commit hook для валидации:

bash#!/bin/bash
# .git/hooks/pre-commit

for md_file in $(git diff --cached --name-only | grep '\.md$'); do
    if [[ -f "$md_file" ]]; then
        if ! ./tools/MD_to_Files.sh -d "$md_file" /tmp/test &>/dev/null; then
            echo "❌ Invalid structure in $md_file"
            exit 1
        fi
    fi
done

echo "✅ All Markdown structures are valid"

GitHub Actions

textname: Generate Project Structure

on:
  push:
    paths:
      - 'docs/project-structure.md'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Generate project files
        run: |
          chmod +x ./tools/MD_to_Files.sh
          ./tools/MD_to_Files.sh -P docs/project-structure.md ./generated

      - name: Commit generated files
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add generated/
          git commit -m "Auto-generate project structure" || true
          git push

GitLab CI

textgenerate-structure:
  script:
    - chmod +x ./tools/MD_to_Files.sh
    - ./tools/MD_to_Files.sh -P docs/structure.md ./output
  artifacts:
    paths:
      - output/
  only:
    changes:
      - docs/structure.md

VS Code Task

json{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Generate from Markdown",
      "type": "shell",
      "command": "./tools/MD_to_Files.sh",
      "args": [
        "${file}",
        "${workspaceFolder}/generated"
      ],
      "presentation": {
        "reveal": "always"
      }
    }
  ]
}

Makefile

makefile.PHONY: generate update clean test

MD2FILES := ./tools/MD_to_Files.sh
INPUT := docs/structure.md
OUTPUT := ./generated

generate:
    $(MD2FILES) -P $(INPUT) $(OUTPUT)

update:
    $(MD2FILES) -U -b $(INPUT) $(OUTPUT)

clean:
    rm -rf $(OUTPUT)

test:
    $(MD2FILES) -d $(INPUT) $(OUTPUT)

AI-ассистенты

Оптимальный prompt для ChatGPT/Claude:

textСоздай структуру проекта для [описание проекта].
Используй следующий формат для MD_to_Files.sh:

# Project Name

## Project Structure

project-name/
├── src/
│ └── main.js
└── package.json

Implementation

src/main.js

javascript
// код

package.json

json
{
«name»: «project-name»
}

textУбедись, что:
- Дерево использует Unicode символы (├─└│)
- Каталоги заканчиваются на /
- Файлы помечены жирным шрифтом: **path/to/file.ext**
- Блоки кода в тройных backticks с языком

🔧 Устранение неполадок

Типичные ошибки

Ошибка: «No tree structures found»

Причина: Markdown не содержит распознаваемого дерева.

Решение:

text# ✓ Правильно
├── src/
│   └── file.js

# ✗ Неправильно
- src/
  - file.js

Ошибка: «Permission denied»

Причина: Нет прав на запись.

Решение:

bash# Проверьте права
ls -la target_directory

# Измените права
chmod 755 target_directory

Ошибка: «File encoding not supported»

Причина: Неподдерживаемая кодировка.

Решение:

bash# Определите кодировку
file -i problem_file.md

# Конвертируйте в UTF-8
iconv -f WINDOWS-1252 -t UTF-8 problem_file.md > fixed_file.md

Диагностика

bash# Подробный вывод с логом
./MD_to_Files.sh -v -l debug.log structure.md ./output

# Поиск ошибок в логе
grep -E "(ERROR|WARNING)" debug.log

# Dry-run для проверки
./MD_to_Files.sh -d -v structure.md ./test

FAQ

Q: Почему код не попал в файлы?

A: Проверьте маркеры файлов:

text# ✓ Правильно
**src/app.js**

javascript
код

text# ✗ Неправильно
src/app.js  # Без жирного шрифта

javascript
код

text</details>

<details>
<summary><b>Q: Как обработать несколько структур?</b></summary>

A: Используйте пакетный режим:

bash
./MD_to_Files.sh -a multi_structures.md ./output

</details>

<details>
<summary><b>Q: Можно ли обновить только конкретные файлы?</b></summary>

A: Да, используйте режим обновления:

bash
./MD_to_Files.sh -U specific_files.md ./existing-project

</details>

<details>
<summary><b>Q: Поддерживаются ли бинарные файлы?</b></summary>

A: Нет, только текстовые файлы. Бинарные файлы нужно добавлять вручную.
</details>

<details>
<summary><b>Q: Как работает с Windows?</b></summary>

A: Используйте WSL (Windows Subsystem for Linux) или Cygwin.

powershell

В WSL

wsl bash MD_to_Files.sh structure.md ./output

</details>

---

## 📚 Документация

### Полная документация

- 📖 [Подробное руководство пользователя](docs/USER_GUIDE.md)
- 🏗️ [Архитектура и логика работы](docs/ARCHITECTURE.md)
- 🔌 [Интеграция и автоматизация](docs/INTEGRATION.md)
- 💡 [Лучшие практики](docs/BEST_PRACTICES.md)
- 🐛 [Troubleshooting](docs/TROUBLESHOOTING.md)

### Дополнительные ресурсы

- [CHANGELOG](CHANGELOG.md) — История изменений
- [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) — Кодекс поведения
- [CONTRIBUTING](CONTRIBUTING.md) — Руководство для контрибьюторов
- [LICENSE](LICENSE) — Лицензия MIT

### Шаблоны

- [Express API Template](templates/express-api.md)
- [React App Template](templates/react-app.md)
- [Python Project Template](templates/python-project.md)
- [Node.js CLI Template](templates/nodejs-cli.md)

---

## 🤝 Contributing

Мы приветствуем вклад в развитие проекта! Вот как вы можете помочь:

### Способы участия

1. 🐛 **Сообщайте о багах** — откройте [issue](https://github.com/paulmann/1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures/issues)
2. 💡 **Предлагайте улучшения** — создайте feature request
3. 📝 **Улучшайте документацию** — исправьте опечатки, добавьте примеры
4. 💻 **Отправляйте Pull Requests** — исправления багов и новые функции

### Процесс контрибьюции

bash

1. Fork репозитория

2. Клонируйте ваш fork

git clone https://github.com/YOUR_USERNAME/1st-Launch-Projects-Code-from-LLM-Responses-in-Markdown-into-Actual-File-Structures.git

3. Создайте ветку для изменений

git checkout -b feature/amazing-feature

4. Внесите изменения и закоммитьте

git commit -m «Add amazing feature»

5. Запушьте в ваш fork

git push origin feature/amazing-feature

6. Откройте Pull Request

### Стандарты кода

- Используйте Shell Check для проверки скриптов
- Добавляйте комментарии к сложной логике
- Следуйте существующему стилю кодирования
- Обновляйте документацию при добавлении функций
- Добавляйте тесты для новой функциональности

### Тестирование

bash

Запустите тесты

./tests/run_tests.sh

Проверьте Shell Check

shellcheck MD_to_Files.sh
«`

📞 Контакты

Автор

Mikhail Deynekin

🌐 Сайт: deynekin.com
📧 Email: mid1977@gmail.com
💼 LinkedIn: linkedin.com/in/mikhail-deynekin

Проект

🐙 GitHub: 1st-Launch-Projects-Code-from-LLM
🐛 Issues: Сообщить о проблеме
💬 Discussions: Обсуждения

🌟 Поддержите проект

Если MD_to_Files.sh помог вам в работе:

⭐ Поставьте звезду на GitHub
🐦 Расскажите о проекте в социальных сетях
📝 Напишите статью или туториал

🙏 Благодарности

Спасибо всем, кто внес вклад в развитие проекта:

@paulmann — оригинальный автор
Всем контрибьюторам — спасибо за Pull Requests
Сообществу — за отзывы и предложения

Связанные проекты

Clean_BOM_Senior — Очистка BOM в PHP файлах

📑 Содержание

🎯 О проекте

Проблема

Решение

Для кого?

✨ Ключевые возможности

🌳 Умный парсинг структуры

💻 Интеллектуальная работа с кодом

🔒 Безопасность и надежность

⚙️ Гибкость настройки

🚀 Быстрый старт

Установка (5 секунд)

Первый запуск (1 минута)

📦 Установка

Метод 1: Git Clone (рекомендуется)

Метод 2: Прямая загрузка

Метод 3: Глобальная установка

Системные требования

Проверка зависимостей

💡 Использование

Базовый синтаксис

Простые примеры

Режимы работы

Дополнительные опции

Комбинации опций

📝 Форматы входных данных

Структура Markdown-документа

Форматы дерева каталогов

Блоки кода

Поддерживаемые языки

Методы связывания кода с файлами

🎬 Примеры

Пример 1: React-приложение

Пример 2: Express API

Express REST API

Пример 3: Python учебный курс

Python Course

Lesson 1

Lesson 2

Пример 4: Обновление существующего проекта

🔗 Интеграция

Git Hooks

GitHub Actions

GitLab CI

VS Code Task

Makefile

AI-ассистенты

Implementation

🔧 Устранение неполадок

Типичные ошибки

Ошибка: «No tree structures found»

Ошибка: «Permission denied»

Ошибка: «File encoding not supported»

Диагностика

FAQ

В WSL

1. Fork репозитория

2. Клонируйте ваш fork

3. Создайте ветку для изменений

4. Внесите изменения и закоммитьте

5. Запушьте в ваш fork

6. Откройте Pull Request

Запустите тесты

Проверьте Shell Check

📞 Контакты

Автор

Проект

🌟 Поддержите проект

🙏 Благодарности

Связанные проекты

Похожее

Добавить комментарийОтменить ответ