﻿---
title: Migrate automated docs
description: If you have automated documentation in Asciidoc (or any other format) that you need to migrate to Elastic docs V3, this guide walks you through the essentials...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/migration/guide/automated
---

# Migrate automated docs
If you have automated documentation in Asciidoc (or any other format) that you need to migrate to Elastic docs V3, this guide walks you through the essentials. Elastic docs V3 (powered by `docs-builder`) allows engineering teams to keep code and reference docs closely integrated for easier updates and greater accuracy.

## Minimum Viable Setup

You can build docs with `docs-builder` using just two files:
1. **`docset.yml`** — Configures the docset for `docs-builder`.
2. **`index.md`** — A Markdown file that will be converted to HTML.

Once you have these files, follow the [Contribute Locally guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/contribute/locally) to get your docs building.

## Syntax

Elastic docs V3 fully supports [CommonMark](https://commonmark.org/) Markdown syntax. In addition, we support:
- Custom directives — our main extension point over markdown (learn more [here](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/syntax))
- A few GitHub flavored markdown extensions (see the list [here](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/syntax))

In most cases, plain Markdown covers basic needs, and directives add extra functionality as needed.
- At a minimum, each page must have an H1 heading:
  ```markdown
  # I'm a heading
  ```
- You can optionally include [frontmatter](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/syntax/frontmatter) for additional metadata.

For more details on custom directives, see the [Syntax Guide](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/syntax).

## Navigation

Your `docset.yml` file configures how `docs-builder` handles navigation. Below is a minimal example:
```yaml
project: 'PROJECT_NAME'

toc:
  - file: index.md
```

For more information, see [Navigation](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2774/configure/content-set/navigation).

## Next steps

That’s all you need to get started migrating automated docs to V3. As you add more pages or custom features, refer to the linked resources for details on configuring your docset, refining navigation, and leveraging the full power of V3 directives.