File extensions and associations

The extension activates on files that VS Code identifies as the AsciiDoc language. Out of the box, the following extensions are registered to that language:

  • .adoc

  • .ad

  • .asciidoc

  • .asc

Prefer .adoc. It is the conventional AsciiDoc file extension, it is the one registered as the AsciiDoc media type, and it is the only extension that every feature of this extension supports without surprises (see Limitations).

Using the extension with another file extension

If your project stores AsciiDoc content under a different extension (for example .txt), you can tell VS Code to treat those files as AsciiDoc with the built-in files.associations setting.

Add this to your workspace or user settings.json:

{
  "files.associations": {
    "*.txt": "asciidoc"
  }
}

You can also set the association per file from the status bar: open the file, click the language indicator in the bottom-right corner, choose Configure File Association for '.txt'…​, and pick AsciiDoc.

Once a file is associated with the AsciiDoc language, most of the extension comes along, because these features key off the language, not the file name:

Limitations

Associating non-.adoc files with AsciiDoc is not fully equivalent to using .adoc. A handful of features look up files by the .adoc extension on disk rather than by language, so they will silently ignore your other files.

The features that rely on the .adoc extension are:

Workspace-wide symbols

The Go to Symbol in Workspace command (Ctrl+T) only indexes */.adoc files. Symbols defined in a .txt file are not discovered, and edits to such files are not watched.

Cross-file cross-reference completion

xref: and << completion gathers candidates from */.adoc files across the workspace. References declared in a .txt file are not offered, and a .txt file will not contribute its anchors to other documents.

Link resolution without an extension

When you Ctrl/Cmd+click a link or include::/xref: target written without an extension (for example xref:chapter[]), the extension resolves it by appending .adoc. A bare target that actually points at a .txt file will not resolve — you must spell out the full file name.

Because of these gaps, using a non-.adoc extension is discouraged. If you can, rename your files to .adoc: it is the official AsciiDoc extension, it keeps every feature working, and your documents will be recognized as AsciiDoc by other tools and platforms (GitHub, GitLab, the Asciidoctor toolchain…) without extra configuration.