.docname {Inclusion vs subdocuments}
.include {docs}

Quarkdown offers two ways to include content from other files: **inclusion** and **subdocumenting**. These approaches differ significantly in how they work and what they are best suited for.

## Inclusion

[Inclusion](including-other-quarkdown-files.qd) via `.include` and `.includeall` evaluates other Quarkdown source files.

The function returns the evaluation result, making it appear as if the target file's content was inserted directly in place of the function call. This is an **opaque operation** because the output contains no traces of the original file.

.example
    > `main.qd`:
    >
    > ```markdown
    > Hello 1
    >
    > .include {other.qd}
    > ```

    > `other.qd`:
    >
    > ```markdown
    > Hello 2
    > ```

    .quarkdownoutput
        .html {<p style="opacity: 0.6">index.html:</p>}

        ```html
        <p>Hello 1</p>
        <p>Hello 2</p>
        ```

### Context

The execution context is ***shared*** between the main file and the included file.

Any customization, function, variable, and other information declared in the main file will be available in the included file, **and vice versa**.

You can optionally restrict this behavior via the [`sandbox`](including-other-quarkdown-files.qd#context-sharing) parameter.

### Circular references

Circular or recursive inclusions are not allowed and will result in an error.

## Subdocuments

[Subdocuments](subdocuments.qd) are independent and referenceable source files.

Subdocuments render as separate resources, and Quarkdown stores links to them in a graph structure.

.example
    > `main.qd`:
    >
    > ```markdown
    > Hello 1
    >
    > [Other](other.qd)
    > ```

    > `other.qd`:
    >
    > ```markdown
    > Hello 2
    > ```

    .quarkdownoutput
        .html {<p style="opacity: 0.6">index.html:</p>}

        ```html
        <p>Hello 1</p>
        <p><a href="./other">Other</a></p>
        ```

        .html {<p style="opacity: 0.6">other.html:</p>}

        ```html
        <p>Hello 2</p>
        ```

### Context

When evaluating subdocuments, the context is ***inherited*** from the referrer.

Any customization and declaration made in the referrer will be available in the subdocument, but not the other way around.

### Circular references

Each subdocument is evaluated only once, so circular and recursive references are allowed.
