Nested Code Block Extraction Prompt Template

This prompt template is designed for the specific job of extracting hierarchically nested code blocks from AI-generated tutorials, documentation, or educational content. The ideal user is a developer building a documentation generator, a coding agent scaffold, or a content pipeline where a model's output contains code examples that themselves include embedded code blocks (e.g., a Markdown tutorial explaining how to write a Dockerfile that contains a shell script). The core challenge is that standard fenced-code-block regex fails when backtick fences are nested, causing extraction to stop at the first closing fence and corrupting the hierarchical structure. This prompt disambiguates inner and outer blocks by enforcing a structured extraction contract.

You should use this prompt when your input text is known to contain at least one level of nested fenced content, and you need to preserve the parent-child relationship between blocks for downstream file generation or rendering. The prompt requires a clear [INPUT] text, an optional [LANGUAGE_HINTS] list to aid disambiguation, and a defined [OUTPUT_SCHEMA] that specifies a tree structure with depth tracking. Do not use this prompt for flat, single-level code block extraction—simpler regex or standard extraction prompts are more cost-effective and less error-prone for that task. This prompt is overkill for responses that only contain inline code or a single fenced block.

Before wiring this into a production pipeline, you must define clear evaluation criteria for fence depth tracking and delimiter pair matching. Common failure modes include misinterpreting four-backtick fences as nested three-backtick fences, losing track of depth when a block contains an odd number of backticks in prose, and failing to reassemble a block when the model's output has a missing closing fence. The next step after reading this playbook is to copy the prompt template, adapt the [OUTPUT_SCHEMA] to match your application's object model, and run it against a golden dataset of intentionally nested examples to calibrate your validation logic.

This prompt template is designed to extract and disambiguate nested fenced code blocks from model responses. It is particularly useful for tutorial and documentation generators where code blocks contain embedded examples within other code blocks. The template instructs the model to identify outer and inner blocks separately, track fence depth, and preserve hierarchical context so that downstream systems can reliably parse the structure without confusing nested delimiters.

codeCopy
You are an expert code block extraction system. Your task is to parse the provided [INPUT_TEXT] and extract all fenced code blocks, including nested blocks where one code block contains another. You must disambiguate nested fences by tracking fence depth and delimiter pairs.

## Input
[INPUT_TEXT]

## Output Schema
Return a valid JSON object conforming to this structure:
{
  "blocks": [
    {
      "id": "string (unique identifier for this block)",
      "depth": "integer (0 for top-level, 1 for first nested level, etc.)",
      "parent_id": "string | null (id of the containing block, null for top-level)",
      "language": "string | null (language tag from opening fence, null if missing)",
      "content": "string (raw content inside the fences, excluding the fence delimiters themselves)",
      "opening_fence": "string (the exact opening fence string, e.g., ```python)",
      "closing_fence": "string (the exact closing fence string, typically ```)",
      "start_line": "integer (line number in [INPUT_TEXT] where the opening fence appears)",
      "end_line": "integer (line number in [INPUT_TEXT] where the closing fence appears)",
      "contains_nested_blocks": "boolean"
    }
  ],
  "extraction_issues": [
    {
      "type": "string (e.g., 'unclosed_fence', 'misaligned_delimiter', 'ambiguous_nesting')",
      "location_line": "integer | null",
      "description": "string"
    }
  ]
}

## Constraints
[CONSTRAINTS]

## Examples
[EXAMPLES]

## Instructions
1. Scan [INPUT_TEXT] line by line to identify all fenced code block delimiters (``` or ~~~).
2. Track fence depth by maintaining a stack of open fences. Each opening fence increases depth; each closing fence decreases depth.
3. Match closing fences to the nearest unmatched opening fence of the same delimiter type and length.
4. For each block, record the language tag if present on the opening fence.
5. If a closing fence is missing, report it in `extraction_issues` and treat the block as extending to the end of input.
6. If fence delimiters are misaligned (e.g., opening with ``` but closing with ~~~), report it and attempt recovery by matching the most recent compatible opener.
7. Preserve all whitespace and indentation within block content exactly as it appears.
8. Do not classify inline code spans (single backticks) as fenced blocks.

To adapt this template, replace the square-bracket placeholders with your specific inputs. [INPUT_TEXT] should contain the full model response or document to parse. [CONSTRAINTS] can specify additional rules such as maximum nesting depth, language filtering, or handling of indented fences. [EXAMPLES] should include one or two few-shot demonstrations showing correct extraction of nested blocks, especially edge cases like triple-nested fences or blocks where the inner block uses a different delimiter style than the outer block. Before deploying, validate the output against the JSON Schema and run eval checks for fence depth tracking accuracy and misaligned delimiter detection.

The nested code block extraction prompt is designed to be a single step within a larger document processing or code generation pipeline. It should not be the first or last step. The typical harness wraps this prompt between a source ingestion step (which provides the raw markdown or text) and a validation step that verifies the structural integrity of the extracted blocks. Because the prompt handles disambiguation of nested fences, the application layer must preserve the raw response exactly as the model outputs it before any downstream parsing occurs. Any pre-processing that normalizes whitespace or escapes backticks will corrupt the fence hierarchy and cause extraction failures.

Wire the prompt into your application with a strict validation layer immediately after the model response. The expected output is a JSON object containing an outer_blocks array and an inner_blocks array, each with language, content, depth, and fence_type fields. Before passing this output to any file writer or database insert, validate that every opening fence has a corresponding closing fence at the same depth, that language tags are present or explicitly null, and that no block's content contains an unescaped fence that would break the nesting hierarchy. If validation fails, log the raw response and the validation error, then retry with the same prompt and a stronger constraint on fence integrity. After two failed retries, escalate the malformed response for human review rather than silently ingesting broken code blocks.

For production deployments, choose a model with strong instruction-following and structured output capabilities. If your provider supports it, use constrained decoding or structured output mode to enforce the JSON schema directly at the token level, bypassing the need for regex-based extraction. When constrained decoding is unavailable, implement a robust JSON extraction fallback that searches for the first complete JSON object in the response, tolerating markdown fences or surrounding prose. Always log the full prompt, response, extraction latency, and validation result for every call. This trace data is essential for debugging fence misalignment issues and for building a golden dataset of nested code block examples that can be used for regression testing when the prompt or model changes.