Add basic content on what's needed to build docs with docs-builder

docs/configure/content-set/navigation.md

@@ -1,3 +1,88 @@
 # Navigation
 
-tbd
+Navigation is managed by a `docset.yml` file. This file has the following structure:
+
+```yaml
+project: 'PROJECT_NAME'
+
+external_hosts:
+  - EXTERNAL_LINKS_HERE
+
+exclude:
+  - 'EXCLUDED_FILES'
+
+toc:
+  - file: index.md
+  - folder: top-level-bucket-a
+    children:
+      - file: index.md
+      - file: file-a.md
+      - file: file-b.md
+  - folder: top-level-bucket-b
+    children:
+      - file: index.md
+      - folder: second-level-bucket-c
+        children:
+          - file: index.md
+```
+
+## `project`
+
+The name of the project.
+
+Example:
+
+```yaml
+project: 'APM Java agent reference'
+```
+
+## `external_hosts`
+
+All links to external hosts must be declared in this section of `docset.yml`.
+
+Example:
+
+```yaml
+external_hosts:
+  - google.com
+  - github.com
+```
+
+## `exclude`
+
+Files to exclude from the TOC. Supports glob patterns.
+
+The following example excludes all markdown files beginning with `_`:
+
+```yaml
+exclude:
+  - '_*.md'
+```
+
+## `toc`
+
+Defines the table of contents (navigation) for the content set. A minimal toc is:
+
+```yaml
+toc:
+  - file: index.md
+```
+
+The table of contents can be created independent of the directory structure of the files it defines. You can use directories to define nesting in the TOC, but you don't have to. For example, both of the following create the same nav structure:
+
+```yaml
+  ...
+  - file: subsection/index.md
+    children:
+      - file: subsection/page-one.md
+      - file: subsection/page-two.md
+```
+
+```yaml
+  ...
+  - folder: subsection
+    children:
+      - file: index.md
+      - file: page-one.md
+      - file: page-two.md
+```

docs/docset.yml

@@ -43,6 +43,9 @@ toc:
       - folder: guide
         children:
           - file: index.md
+          - file: automated.md
+          - file: tooling.md
+          - file: bug-bash.md
           - file: file-structure.md
           - file: mapping.md
   - folder: configure

docs/migration/guide/automated.md

@@ -0,0 +1,46 @@
+# Migrate Automated Content to V3
+
+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](../../contribute/locally.md) 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](../../syntax/md-extensions.md#directives))
+* A few GitHub flavored markdown extensions (see the list [here](../../syntax/md-extensions.md#github-flavored-markdown))
+
+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](../../syntax/frontmatter.md) for additional metadata.
+
+For more details on custom directives, see the [Syntax Guide](../../syntax/index.md).
+
+## 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](../../configure/content-set/navigation.md).
+
+## 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.

docs/migration/guide/bug-bash.md

@@ -0,0 +1,58 @@
+# Build migrated content sets for Bug Bashes
+
+The following content sets are available for pre-migration testing:
+
+* [elasticsearch.md](https://github.com/elastic/elasticsearch.md)
+* [integration-docs.md](https://github.com/elastic/integration-docs.md)
+* [kibana.md](https://github.com/elastic/kibana.md)
+* [logstash.md](https://github.com/elastic/logstash.md)
+* [machine-learning.md](https://github.com/elastic/machine-learning.md)
+* [observability-docs.md](https://github.com/elastic/observability-docs.md)
+
+## Local directory structure
+
+Assuming the following directory structure:
+
+```markdown
+{GitHub_Repo_Dir}/
+├── tools/
+│   ├── docs-builder-mac-arm64.zip
+│   └── docs-builder
+├── elasticsearch.md
+├── observability-docs.md
+└── kibana.md
+```
+
+You can build migrated content sets on a Mac by running the following commands.
+
+```{tip}
+For other systems, see [Contribute locally](../../contribute/locally.md)
+```
+
+```bash
+# move to GitHub dir
+cd {GitHub_Repo_Dir}
+
+# clone req'd repos
+git clone https://github.com/elastic/elasticsearch.md.git
+git clone https://github.com/elastic/observability-docs.md.git
+git clone https://github.com/elastic/kibana.md.git
+
+# move back to GitHub dir
+cd {GitHub_Repo_Dir}
+mkdir tools
+cd tools
+
+# mac-specific
+curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
+unzip docs-builder-mac-arm64.zip
+
+# Build ES Guide
+./docs-builder serve -p ../elasticsearch.md/docs
+
+# Build Obs Guide
+./docs-builder serve -p ../observability-docs.md/docs
+
+# Build Kib Guide
+./docs-builder serve -p ../kibana.md/docs
+```

docs/migration/guide/index.md

@@ -1,66 +1,7 @@
 # Migration Guide
 
-How to migrate content from Asciidoc to V3.
+Migrate content from Asciidoc to V3
 
-## Migration tooling
-
-Use the [adoc-to-md](https://github.com/elastic/adoc-to-md) conversion tool to migrate content sets from Asciidoc syntax to docs-builder syntax. Instructions to use the tool are in the readme file.
-
-After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder.
-
-## Building migrated content sets for the bug bash
-
-Assuming the following directory structure:
-
-```markdown
-{GitHub_Repo_Dir}/
-├── tools/
-│   ├── docs-builder-mac-arm64.zip
-│   └── docs-builder
-├── elasticsearch.md
-├── observability-docs.md
-└── kibana.md
-```
-
-You can build migrated content sets on a Mac by running the following commands.
-
-```{tip}
-For other systems, see [Contribute locally](../../contribute/locally.md)
-```
-
-```bash
-# move to GitHub dir
-cd {GitHub_Repo_Dir}
-
-# clone req'd repos
-git clone https://github.com/elastic/elasticsearch.md.git
-git clone https://github.com/elastic/observability-docs.md.git
-git clone https://github.com/elastic/kibana.md.git
-
-# move back to GitHub dir
-cd {GitHub_Repo_Dir}
-mkdir tools
-cd tools
-
-# mac-specific
-curl -LO https://github.com/elastic/docs-builder/releases/latest/download/docs-builder-mac-arm64.zip
-unzip docs-builder-mac-arm64.zip
-
-# Build ES Guide
-./docs-builder serve -p ../elasticsearch.md/docs
-
-# Build Obs Guide
-./docs-builder serve -p ../observability-docs.md/docs
-
-# Build Kib Guide
-./docs-builder serve -p ../kibana.md/docs
-```
-
-## Pre-migrated content sets available for testing:
-
-* [elasticsearch.md](https://github.com/elastic/elasticsearch.md)
-* [integration-docs.md](https://github.com/elastic/integration-docs.md)
-* [kibana.md](https://github.com/elastic/kibana.md)
-* [logstash.md](https://github.com/elastic/logstash.md)
-* [machine-learning.md](https://github.com/elastic/machine-learning.md)
-* [observability-docs.md](https://github.com/elastic/observability-docs.md)
+* [Migrate automated documentation](./automated.md) — for developers
+* [Migrate narrative content manually](./tooling.md) — handled by the docs team
+* [Build pre-migrated content sets](./bug-bash.md) — for the docs team bug bash

docs/migration/guide/tooling.md

@@ -0,0 +1,5 @@
+# Run migration tooling
+
+Use the [adoc-to-md](https://github.com/elastic/adoc-to-md) conversion tool to migrate content sets from Asciidoc syntax to docs-builder syntax. Instructions to use the tool are in the readme file.
+
+After running the migration tool, you can move and manipulate files while viewing a live preview of the content with docs-builder.

docs/syntax/frontmatter.md

@@ -6,6 +6,5 @@ Supported frontmatter includes:
 
 | Frontmatter         | Learn more                  |
 | ------------------- | --------------------------- |
-| `title`             | See [title](./titles.md)    |
 | `navigation_title`  | See [title](./titles.md)    |
 | `applies`           | See [product availability](./applies.md) |

docs/syntax/titles.md

@@ -14,13 +14,13 @@ Each page is required to at least define a level one heading.
 
 This title is used both by the documentation navigation
 
-* Left hand site 
+* Left hand site
 * Navigational elements such as breadcrumbs and previous/next links.
 
-As well as when using the autolink naming feature e.g:
+As well as when using the [auto text links](./links.md#auto-text-links), e.g:
 
 ```markdown
-[titles.md]()
+[](titles.md)
 ```
 
 Generated link text: [](titles.md)