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.

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.

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 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.

Links between pages

Documents in a content repository link to each other with paths that only work on the original site — /content/product/mmp/webhooks/integrating-cloud-events.md, ../index.md, or a clean URL such as /content/product/mmp/graphql where the file on disk is graphql/index.md. The connector resolves each of those against the folder and rewrites them so they work in AGO:

• A link to a file imported by this source points to that AGO document.
• A link to a page that exists on the site but not in this source — another product’s folder, an OpenAPI specification, a route with no file behind it — becomes a link to your public site, provided External Link Base URL is set.
• Links to other sites, anchors (#section), email addresses, and paths that resolve to nothing are left as they are.

Anchors are kept, so /content/product/mmp/graphql#queries still lands on the right section.

Setup

1. Create the source

   1. Navigate to Knowledge → Sources
   2. Click Create Source
   3. Select File Directory as the source type
2. 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): the address where the same content is published. Each document then links to {base}/{relative path without extension} — a file at api/intro.md with a base of https://docs.example.com links to https://docs.example.com/api/intro. An index file is the address of its own folder, so graphql/index.md links to https://docs.example.com/graphql. This base is also what lets the connector rewrite links to pages outside the imported folder.
3. Sync

   1. Click Sync to import the folder
   2. Review the imported documents in the source tree

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 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

OpenAPI Integration

Import a single OpenAPI specification

Knowledge Source Management

Sync scheduling, display settings, and troubleshooting