LLM Response Formatting Guide for MD to Files Parser

Professional Guidelines for Structured Code Project Generation

Version: 1.0
Document Date: 2025-10-30
Compatibility: MD to Files v6.0.1+
Author: Mikhail Deynekin
Website: https://deynekin.com

Executive Summary

This document defines the standardized markdown formatting requirements for AI/LLM code generation responses to ensure optimal parsing and automatic project structure creation using the MD to Files script. Following these guidelines enables seamless conversion of conversational code generation into production-ready file hierarchies.

Purpose & Benefits
Required Components
File Placement Markers
Directory Tree Structure
Code Block Format
Usage Instructions
Example Prompt
Validation Checklist
Troubleshooting

Purpose & Benefits

Why This Matters

When requesting code generation from Large Language Models (LLMs), responses typically include:

Multiple code files scattered throughout the response
File organization suggestions scattered across explanatory text
Inconsistent formatting across different code blocks
Challenges in extracting actionable file structure

Benefits of Standardized Formatting

Automation: Direct conversion from response to working project structure
Accuracy: Eliminates manual file organization errors
Speed: Creates project in seconds instead of minutes
Consistency: Ensures reproducible results across multiple requests
Scalability: Supports complex project hierarchies with ease

Required Components

Mandatory Elements

Every LLM response using the MD to Files parser MUST contain:

Component	Purpose	Format
Directory Tree	Project structure visualization	Markdown tree with `├──`, `│`, `└──`
File Markers	Link files to code blocks	`[file name]: path/to/file.ext`
Code Blocks	Actual file content	Fenced code blocks with language identifier
Language Tags	Enable syntax highlighting	Python: ```python, JavaScript: ```js

Parser note (v6.0.1+): the directory tree is documentation for the reader — the script builds folders from the paths in the file markers. A tree alone produces no files, and a folder that contains no marked file is not created.

Optional Elements

Brief descriptions for each file section
Comments explaining key functionality
Installation or setup instructions
Documentation and README content

File Placement Markers

Marker Format

The parser recognizes three file marker syntaxes:

1. C/C++/JavaScript Style (Recommended)

// [file name]: src/components/Button.jsx

2. Python/Bash Style

# [file name]: app/models.py

3. Batch/Windows Style

REM [file name]: scripts/setup.bat

Marker Placement Rules

CRITICAL: Place the file marker immediately after the opening code fence, before any code content:

# [file name]: src/main.py
import sys

def main():
    print("Hello World")

if __name__ == "__main__":
    main()

✅ CORRECT: Marker on first line after fence
❌ INCORRECT: Marker after imports or comments
❌ INCORRECT: Marker outside code block

Marker Syntax Rules

Exact format: [file name]: (case-sensitive)
Colon required: Must include : after [file name]
Path format: Use forward slashes / (works on all platforms)
No spaces in comments: Use # [file name]: not #[file name]:
Path normalization: Script automatically removes leading ./ and /

Valid Path Examples

[file name]: src/main.py
[file name]: config/settings.json
[file name]: tests/unit/test_auth.py
[file name]: frontend/pages/index.tsx
[file name]: README.md
[file name]: .gitignore

Invalid Path Examples

[file name]: /usr/local/bin/script.sh  ❌ Absolute path
[file name]: ../../../main.py          ❌ Parent directory traversal
[file name]: <script>alert('xss')</script>  ❌ Script injection
[file name]: path/to/file | rm -rf /  ❌ Command injection

Directory Tree Structure

Markdown Tree Format

The parser recognizes standard markdown tree notation:

project/
├── README.md
├── src/
│   ├── main.py
│   ├── utils.py
│   └── __init__.py
├── tests/
│   ├── test_main.py
│   └── test_utils.py
└── config/
    └── settings.json

Tree Syntax Requirements

Symbol	Meaning	Usage
`├──`	Intermediate branch	Middle items in directory
`│`	Vertical line	Continuation indicator
`└──`	Last branch	Final item in directory
`/`	Directory suffix	Indicates folder (recommended)

Tree Placement

MUST be in a code block: Wrap in triple backticks ```
Position: Include once near project description or as first visual element
Language identifier: Optional but recommended as text or markdown

Tree Block Example

project/
├── src/
│   ├── main.py
│   └── utils.py
└── tests/
    └── test_main.py

Alternative Tree Formats (Also Supported)

The parser handles multiple tree variations:

project/
|-- src/
|   |-- main.py
|   +-- utils.py
+-- tests/
    +-- test_main.py

Code Block Format

Standard Code Block Structure

# [file name]: src/app.py
"""
Application entry point.
Handles initialization and routing.
"""

def initialize():
    """Initialize the application."""
    print("Starting application...")

Complete Template

[opening fence + language]
[file marker]
[optional docstring/comment]
[actual code content]
[closing fence]

Language Identifiers

Use appropriate language identifier for syntax highlighting:

Language	Identifier	Example
Python	`python`	```python
JavaScript/Node	`javascript` or `js`	```js
TypeScript	`typescript` or `ts`	```ts
Bash/Shell	`bash` or `sh`	```bash
JSON	`json`	```json
YAML	`yaml` or `yml`	```yaml
PHP	`php`	```php
SQL	`sql`	```sql
HTML	`html`	```html
CSS	`css`	```css

Code Block Best Practices

Complete content: Provide full, working code - not fragments
Comments: Include docstrings and inline comments for clarity
Imports/Dependencies: Include all necessary import statements at the top
Error handling: Add try-catch or error handling where appropriate
Consistency: Use consistent indentation (4 spaces for Python, 2 for JS)

Usage Instructions

Step 1: Prepare Your LLM Request

Add this prompt injection to your code generation request:

Please format your response to be compatible with MD to Files parser (v6.0.1+).

Requirements:
- Include a complete project directory tree at the beginning
- Wrap each file's content in a markdown code block with language identifier
- Add file marker comment on the first line: [file name]: path/to/file.ext
- Use proper tree syntax with ├──, │, └── symbols
- Ensure all paths use forward slashes (/)
- Provide README.md with setup instructions

Step 2: Verify Response Format

Check response contains:

Directory tree with project/ as root
File markers in [file name]: path format
All code in fenced code blocks
Language identifiers on fences
Proper nesting with tree symbols

Step 3: Process with MD to Files

# Dry-run to verify structure
./MD_to_Files.sh -d response.md ./output

# Create actual project
./MD_to_Files.sh -v response.md ./output

# With all options
./MD_to_Files.sh -vbP response.md ./project

Example Prompt

Recommended Prompt Template

Save this as a template for consistent requests:

# Code Generation Request with MD to Files Compatibility

Please generate a [PROJECT_TYPE] project with the following specifications:

## Requirements
[Your specific requirements here]

## Output Format Requirements

Please structure your response as follows:

1. **Project Overview**: Brief description (2-3 sentences)

2. **Project Structure**: Display complete directory tree in the format:

project/ ├── directory1/ │ ├── file1.ext │ └── file2.ext └── directory2/ └── file3.ext


3. **File Contents**: For each file, provide:
- Code block with appropriate language identifier
- File marker as first line: `[file name]: path/to/file.ext`
- Complete, production-ready code
- Comments and docstrings for clarity

4. **Dependencies**: List required packages/libraries

5. **Setup Instructions**: Step-by-step setup guide

## Compatibility Note
Format response for compatibility with MD to Files Parser (v6.0.1+) to enable automated project structure generation.

Concrete Example Request

Generate a Python REST API with FastAPI for a TODO application.

Requirements:
- SQLAlchemy ORM for database
- PostgreSQL database
- JWT authentication
- Pydantic models for validation
- Full CRUD operations for todos
- User authentication endpoints

Format response for MD to Files Parser (v6.0.1+):
- Include project tree at start
- Each file in code block with [file name]: path/to/file.ext marker
- Production-ready code with error handling
- Include setup instructions and requirements.txt

Validation Checklist

Before Processing Response

Use this checklist to verify response quality:

Project Structure Validation
=============================

□ Project tree starts with "project/"
□ Tree uses ├──, │, └── symbols
□ Tree is in a code block
□ All directories end with "/"
□ All files listed in tree have corresponding code blocks

File Marker Validation
======================

□ Each code block has [file name]: marker
□ Marker is on first line after opening fence
□ Marker format matches exactly: [file name]: path/to/file.ext
□ All paths use forward slashes "/"
□ No absolute paths (no leading /)
□ No parent directory traversal (no ../)
□ File extensions match actual file types

Code Block Validation
=====================

□ Code blocks use triple backticks (```)
□ Language identifier present (python, js, etc.)
□ Code is complete and functional
□ No syntax errors or incomplete statements
□ Imports/dependencies at top of file
□ Proper indentation maintained
□ Comments and docstrings included

Content Validation
==================

□ README.md or setup instructions included
□ All referenced files in tree are defined
□ No duplicate file definitions
□ Configuration files (.env, .gitignore) included
□ Package dependencies specified
□ Paths are logically organized

Quick Validation Script

#!/bin/bash
# Validate markdown structure for MD to Files compatibility

file="$1"

echo "Validating: $file"

# Check for project tree
grep -q "^project/" "$file" && echo "✓ Project root found" || echo "✗ Missing project root"

# Check for tree symbols
grep -q "├──" "$file" && echo "✓ Tree structure found" || echo "⚠ Warning: No tree symbols"

# Check for file markers
marker_count=$(grep -c "\[file name\]:" "$file" || echo 0)
echo "✓ Found $marker_count file markers"

# Check for code blocks
block_count=$(grep -c "^\\`\\`\\`" "$file" || echo 0)
echo "✓ Found $block_count code blocks (verify marker count matches)"

echo "Validation complete"

Troubleshooting

Common Issues and Solutions

Issue 1: "No project structures found in markdown"

Symptom: Script reports no valid tree structure

Causes:

Tree not in code block
Tree doesn't start with project/
Using incorrect symbols

Solution:

# CORRECT

project/ ├── src/ │ └── main.py


# INCORRECT - no backticks
project/
├── src/
│   └── main.py

Issue 2: "File name too long" error

Symptom: Files not created, error about filename length

Causes:

File marker contains extra text
Path exceeds 255 characters
Marker format incorrect

Solution:

# [file name]: src/components/button.py
# ✓ Correct - clean, concise path

# [file name]: This is a component for the button in the UI section that handles user clicks and sends events: button.py
# ✗ Wrong - contains description

Issue 3: Files not extracted despite markers

Symptom: Tree created but no code files

Causes:

File marker not on first line of code block
Marker format has typos
Code block language missing

Solution:

# WRONG - marker after imports
# [file name]: src/main.py
import sys
import os

# CORRECT - marker immediately after fence
# [file name]: src/main.py
import sys
import os

Issue 4: Duplicate output with --help or --version

Symptom: Help text or version repeats multiple times with errors

Solution: Update to version 6.0.1 or later:

./MD_to_Files.sh --help  # Should output once, cleanly
./MD_to_Files.sh --version  # Should output once, cleanly

Integration with CI/CD

GitHub Actions Example

name: Generate Project from LLM Response

on: [push]

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Download MD to Files
        run: |
          wget https://raw.githubusercontent.com/YOUR_REPO/MD_to_Files.sh
          chmod +x MD_to_Files.sh
      
      - name: Validate Response Format
        run: |
          ./MD_to_Files.sh -d llm_response.md ./validate_output
      
      - name: Generate Project
        run: |
          ./MD_to_Files.sh -vbP llm_response.md ./generated_project
      
      - name: Upload Artifacts
        uses: actions/upload-artifact@v3
        with:
          name: generated-project
          path: generated_project/

Best Practices

Do's ✅

✅ Always include a README.md with setup instructions
✅ Use descriptive file paths that reflect project organization
✅ Include docstrings and inline comments
✅ Test the response format before processing
✅ Keep file paths under 200 characters
✅ Use consistent naming conventions (snake_case, camelCase, etc.)
✅ Include requirements.txt, package.json, or equivalent dependency files
✅ Verify all imports and dependencies are available

Don'ts ❌

❌ Don't omit the project tree
❌ Don't place markers inside code (after line 1)
❌ Don't use absolute paths or parent directory traversal
❌ Don't include multiple markers per code block
❌ Don't use inconsistent path separators (mix / and \)
❌ Don't provide incomplete or non-functional code
❌ Don't forget language identifiers on code fences
❌ Don't skip configuration files (.env, .gitignore, etc.)

Version Compatibility

MD to Files Version	Status	Support
6.0.1+	✅ Current	Full support for all features
6.0.1	⚠️ Legacy	Dupliation issues, use 6.0.1+
5.1.0-5.1.1	❌ Deprecated	Critical bugs, upgrade required

Support & Feedback

For issues, questions, or feature requests:

Author: Mikhail Deynekin
Email: mid1977@gmail.com
Website: https://deynekin.com
License: PolyForm Noncommercial 1.0.0

Document History

Version	Date	Changes
1.0	2025-10-30	Initial release with comprehensive guidelines

Last Updated: 2025-10-30
Compatibility: MD to Files v6.0.1+

FilesExpand file tree

PROMPT_GUIDE.md

Latest commit

History

PROMPT_GUIDE.md

File metadata and controls

LLM Response Formatting Guide for MD to Files Parser

Professional Guidelines for Structured Code Project Generation

Executive Summary

Table of Contents

Purpose & Benefits

Why This Matters

Benefits of Standardized Formatting

Required Components

Mandatory Elements

Optional Elements

File Placement Markers

Marker Format

1. C/C++/JavaScript Style (Recommended)

2. Python/Bash Style

3. Batch/Windows Style

Marker Placement Rules

Marker Syntax Rules

Valid Path Examples

Invalid Path Examples

Directory Tree Structure

Markdown Tree Format

Tree Syntax Requirements

Tree Placement

Tree Block Example

Alternative Tree Formats (Also Supported)

Code Block Format

Standard Code Block Structure

Complete Template

Language Identifiers

Code Block Best Practices

Usage Instructions

Step 1: Prepare Your LLM Request

Step 2: Verify Response Format

Step 3: Process with MD to Files

Example Prompt

Recommended Prompt Template

Concrete Example Request

Validation Checklist

Before Processing Response

Quick Validation Script

Troubleshooting

Common Issues and Solutions

Issue 1: "No project structures found in markdown"

Issue 2: "File name too long" error

Issue 3: Files not extracted despite markers

Issue 4: Duplicate output with --help or --version

Integration with CI/CD

GitHub Actions Example

Best Practices

Do's ✅

Don'ts ❌

Version Compatibility

Related Documentation

Support & Feedback

Document History