# Content Types

> The four content-type flavors a source can pick — plain, Obsidian vault, Notion export and OpenAPI/Swagger — and what each one transforms before chunking.

- Updated: 2026-10-10
- Source: https://contextator.com/en/docs/content-types/
- Language: en-US
- Author: Muhammet Şafak

---
Documentation exported from another tool is Markdown, but carries that tool's own syntax. A source's
**content type** — sometimes called its flavor — applies a small transform so an agent reads plain
Markdown regardless of where a file came from. Your files are never modified: not the mounted folder,
not the git checkout, not the uploaded tree.

## Every file becomes Markdown first — one exception

Before a content type runs at all, every file a source reads is converted to Markdown by its own file
type: `.html`/`.htm`, `.docx`, `.pdf` and `.csv` are each converted; `.md`, `.mdx` and `.txt` pass
through unchanged, already being text. This is what lets a Confluence page or a crawled
documentation-site page arrive as Markdown too — see [Confluence](/en/docs/confluence/) and
[Documentation Site Source](/en/docs/documentation-site-source/). The content type below is a *second*
transform, applied to that Markdown, and depends on where the files came from rather than what format
they were in.

The one exception is **OpenAPI / Swagger**: a `.yaml`, `.yml` or `.json` specification under that
content type is never converted to Markdown at all. It is read as structured data and rendered straight
into one document per operation — see below.

## The four content types

| Content type | Use it for | What it does |
|---------------|-----------|---------------|
| **Plain Markdown / text** | Everything normal — the default | Nothing |
| **Obsidian vault** | An Obsidian vault, however it arrived | Rewrites `[[wikilinks]]`, callouts and comments |
| **Notion export** | A Notion *Export → Markdown & CSV* zip | Strips the 32-character page id Notion appends to file and folder names, and fixes the links pointing at them |
| **OpenAPI / Swagger** | A source holding API specifications | Reads `.yaml`, `.yml` and `.json` as specifications and turns one file into one document per operation |

**Add source** picks this per source: the dashboard's **Obsidian vault** tab selects the Obsidian
content type for you; a Notion export zip needs **Upload files** with **Notion export** chosen
explicitly, since the tab does not imply it; **OpenAPI / Swagger** must always be chosen deliberately.
See [Document Sources](/en/docs/document-sources/).

## Obsidian vault

Every wikilink form becomes a standard Markdown link, `> [!NOTE]` becomes `> **Note:**` so the callout
kind stays searchable in plain text, and `%%comments%%` are removed. The full table of rewrites is on
[Obsidian Vaults](/en/docs/obsidian-vaults/).

## Notion export

A Notion export zip names files and folders like this:

```
Getting started 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d.md
Engineering 9f8e7d6c5b4a39281706f5e4d3c2b1a0/Runbook 0a1b2c3d….md
```

With **Notion export** selected, the 32-character id is removed from the links that point at those files, and — for uploads and unpacked archives — from every path segment, so documents read as:

```
Getting started.md
Engineering/Runbook.md
```

For the live API instead of an export zip, use a [Notion](/en/docs/notion/) source instead — it needs
no content type, since there is no id to strip from an API response.

## OpenAPI / Swagger

This is the one content type that does something a transform alone cannot: it says a file is **not one
document**. A specification is indexed as **one document per `(method, path)` operation** — path,
method, summary, parameters, request and response schemas and examples, each under its own heading, so
a search hit carries a breadcrumb like `GET /pets/{petId} > Responses > 200` and `search_docs` returns
the endpoint, not the file.

- **`.yaml`, `.yml` and `.json` are selectable only under this content type.** No extension implies a
  specification on its own — a `.yaml` might just as well be a Helm values file or a CI config — so
  choosing this content type is what makes those extensions readable at all, on that source alone.
- **Each document is stored at `<file>/<method>-<path>`**, e.g. `api/petstore.yaml/get-pets-petId`. The
  path comes from the method and the URL path alone, so re-indexing the same specification, even
  reformatted, lands on the same documents. A path segment longer than 120 characters is shortened and gets a hash of the method and path appended, so very long paths stay distinct.
- **`$ref` is resolved within the file.** A recursive schema renders until it points back at itself and
  says so; anything past eight levels deep says it stopped there. A reference into another file is
  named rather than followed.
- **Markdown beside the specifications stays Markdown** — a `README.md` in the same source is still one
  ordinary document.
- **A file that is not a valid specification is refused by name**, the same way an unconvertible PDF
  is — the reason is shown on the source's row, and the rest of the source indexes normally. So is one
  written to make a renderer fail, such as a self-referential example or a `$ref` that will not decode:
  nothing a specification can contain fails the whole run.
- **Swagger 2.0 is read as well as OpenAPI 3**, `definitions`, `in: body` parameters and
  `host`/`basePath` included; a 3.1 path item that is itself a `$ref` is followed.
- **A specification is measured against `MAX_SPEC_FILE_BYTES` (8 MiB) before it is read** — its own
  ceiling, well below the one for converted files, because parsing one produces an object graph around
  fifty-five times the size of the file, held in memory for as long as that file is being indexed. At
  the default ceiling that is roughly **400 MB of heap** while one specification indexes; lower the
  variable on a container that cannot spare it. See [Configuration](/en/docs/configuration/).
- **One rendered document is capped at 2 000 lines, and one specification at 5 000 operations.** Neither
  is reachable by a real API — the largest published specifications run to roughly a thousand
  operations — and both exist because the file-size ceiling bounds the parse, not what a file asks to
  be rendered into.
- Two releases of the same API in one project do not collide: give each specification's source a
  [version](/en/docs/document-sources/), and `v2/openapi.yaml/get-pets` and `v3/openapi.yaml/get-pets`
  are separate documents that `search_docs`'s `version` filter tells apart.

## Changing the content type later

Editing a source and picking another content type has one subtlety worth knowing: Contextator decides
what to re-embed by hashing each file's **raw bytes**, before either transform runs. Changing the
content type alone would never touch a file whose bytes did not change — so instead, changing it
**drops that source's stored hashes and queues an index run**, and every file is re-processed with the
new transform. The practical consequence is that changing the content type of a large source costs a
full re-embed of it; changing its language or version does the same, while other settings that change what the source yields (path, branch, subdirectory, file types) at most queue an incremental run. Path cleaning happens only when files are written to disk (upload and archive unpacking), so a local or git source keeps the ids in its file names, and changing the content type later does not rename files already stored.

## Picking the right one

- If in doubt, leave a source on **Plain Markdown / text** — the other transforms only help when their
  syntax is actually present, and never improve ordinary Markdown.
- A Notion export zip needs **Notion export** chosen explicitly on an **Upload** source; nothing infers
  it from the file names.
- **OpenAPI / Swagger** must be chosen deliberately, and it is what makes `.yaml`, `.yml` and `.json`
  selectable in **File types** at all on that source.
