> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# File Directory Integration

> Import a local folder of mixed files, parsing each one by its type

Import a folder of files from the server and let AGO parse each file by its type. Point the source at a directory and every supported file inside it (including subfolders) becomes a knowledge document. Use this when your content already lives as files on disk — a docs repository, an export, or a mixed folder of Markdown, HTML, OpenAPI specs, and office documents.

<Note>
  This connector is for **on-premise (self-hosted) deployments**. It reads from the server's local filesystem, so the folder you point it at must be available on the machine running AGO (for example a mounted content volume). It isn't available on the AGO cloud.
</Note>

## How files are parsed

Each file is handled according to its extension:

| File type         | Extensions                                                                                                         | How it is imported                              |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
| Markdown / text   | `.md`, `.markdown`, `.mdx`, `.txt`, `.text`                                                                        | Used directly — the content is already Markdown |
| HTML              | `.html`, `.htm`                                                                                                    | Converted to Markdown                           |
| OpenAPI / Swagger | `.json` declaring `openapi` or `swagger`                                                                           | Expanded into one document per API operation    |
| Other documents   | `.pdf`, `.doc`, `.docx`, `.docm`, `.ppt`, `.pptx`, `.xls`, `.xlsx`, `.csv`, `.xml`, `.epub`, and any other `.json` | Text extracted and converted to Markdown        |

A `.json` file that doesn't declare `openapi` or `swagger` is treated as a regular document (text extracted). Files with any other extension are skipped, and empty files are ignored.

The document title comes from the first Markdown heading, or the file name when there is none.

## Markdoc content

If your Markdown uses [Markdoc](https://markdoc.dev) tags (`{% … %}`), the connector cleans them up automatically — it turns on whenever it sees `{%` in a file. It:

* **Resolves `{% partial file="/…" /%}` includes** by inlining the referenced file (recursively). Partial paths are absolute from the site root, so set **Markdoc Root** to your portal's root folder when the shared partials live outside the imported directory. It defaults to the directory path.
* **Evaluates `{% if %}` / `{% else %}` conditions** against the teams in **Markdoc RBAC Teams**, keeping only the matching branch. This is for role-gated content (for example sections shown only to authenticated users). The default is the authenticated operator view, which keeps the most content. To import the public view instead, set the teams to a value your content's conditions don't grant access to (for example `anonymous`), so authenticated-only sections are dropped. You can create two sources over the same folder with different teams to feed different audiences.
* **Simplifies the rest**: admonitions become labelled callouts, images become Markdown images, and navigation widgets (cards) are dropped.

YAML frontmatter is removed from each Markdoc-processed file.

## Images

Images referenced in Markdown (`![alt](/img/diagram.png)`) are imported and served by AGO so they display in the knowledge base. For each local image, the connector stores the file as a document attachment and rewrites the link to AGO's served URL. Site-root-absolute paths (`/img/…`) are resolved against **Image Root** (defaults to the Markdoc Root, then the directory path); relative paths resolve next to the document. Images already served from a URL (for example `https://…` or `data:` URIs) are left as they are. Turn this off with the **Import Images** toggle.

## Setup

<Steps>
  <Step title="Create the source">
    1. Navigate to **Knowledge** → **Sources**
    2. Click **Create Source**
    3. Select **File Directory** as the source type
  </Step>

  <Step title="Configure the directory">
    Fill in the configuration fields:

    * **Directory Path** (required): the folder to scan. It is read recursively, including subfolders.
    * **Include Patterns** (optional): glob patterns to limit which files are imported, for example `**/*.md`. Leave empty to import every supported file.
    * **Exclude Patterns** (optional): glob patterns to skip, for example `drafts/*` or `**/*.tmp`.
    * **External Link Base URL** (optional): when set, each document links to `{base}/{relative path without extension}`. For a file at `api/intro.md` and a base of `https://docs.example.com`, the link is `https://docs.example.com/api/intro`.
  </Step>

  <Step title="Sync">
    1. Click **Sync** to import the folder
    2. Review the imported documents in the source tree
  </Step>
</Steps>

## Keeping content in sync

On each sync, AGO re-reads the directory. New and changed files are imported, and documents whose files were removed from the folder are deleted. Enable [auto-sync scheduling](../features/knowledge-source-management#auto-sync-scheduling) to refresh the source on a schedule.

## Notes

* The directory path is read from the AGO backend's filesystem, so the folder must be reachable by the server.
* Include and exclude patterns are matched against each file's path relative to the directory, using `*` and `?` glob wildcards. Exclude patterns take priority over include patterns.

## Related

<CardGroup cols={2}>
  <Card title="OpenAPI Integration" icon="code" href="/data-connector/openapi-integration">
    Import a single OpenAPI specification
  </Card>

  <Card title="Knowledge Source Management" icon="database" href="/features/knowledge-source-management">
    Sync scheduling, display settings, and troubleshooting
  </Card>
</CardGroup>