Migration and Syntax docs updates (#416)

* various internal docs improvements

* fix bug; add mv docs

* more bugs

* last bug

docs/contribute/move.md

@@ -0,0 +1,31 @@
+# Move files and folders
+
+When you move a source file or folder, you must also update all inbound and outbound links to reflect the new file location. `docs-builder` provides tooling to handle this step for you.
+
+## `docs-builder mv`
+
+Move a file or folder from one location to another and update all links in the documentation. For example:
+
+```
+docs-builder mv ./old-location/ia.md ./new-location/ia.md
+```
+
+:::{important}
+The `docset.yml` and `toc.yml` files are not automatically updated when using this tool. You must update these references manually.
+:::
+
+## `docs-builder mv --help`
+
+```
+Usage: mv [arguments...] [options...] [-h|--help] [--version]
+
+Move a file or folder from one location to another and update all links in the documentation
+
+Arguments:
+  [0] <string?>    The source file or folder path to move from
+  [1] <string?>    The target file or folder path to move to
+
+Options:
+  --dry-run <bool?>      Dry run the move operation (Default: null)
+  -p|--path <string?>    Defaults to the`{pwd}` folder (Default: null)
+```

docs/docset.yml

@@ -18,6 +18,7 @@ external_hosts:
   - google.com
   - checkvist.com
   - commonmark.org
+  - github.io
 exclude:
   - '_*.md'
 subs:
@@ -30,6 +31,7 @@ toc:
       - file: index.md
       - file: locally.md
       - file: on-the-web.md
+      - file: move.md
   - folder: migration
     children:
       - file: index.md
@@ -44,10 +46,9 @@ toc:
       - folder: guide
         children:
           - file: index.md
+          - file: working-in-docs-content.md
           - file: automated.md
           - file: tooling.md
-          - file: bug-bash.md
-          - file: file-structure.md
           - file: mapping.md
   - folder: configure
     children:
@@ -68,8 +69,8 @@ toc:
   - folder: syntax
     children:
       - file: index.md
-      - file: md-extensions.md
       - file: admonitions.md
+      - file: applies.md
       - file: automated_settings.md
       - file: code.md
       - file: comments.md
@@ -82,7 +83,6 @@ toc:
       - file: line_breaks.md
       - file: links.md
       - file: passthrough.md
-      - file: applies.md
       - file: sidebars.md
       - file: substitutions.md
       - file: sundries.md

docs/migration/engineering.md

@@ -1,4 +1,4 @@
-# Reference docs guidelines
+# New reference guidelines
 
 ## Engineering ownership of reference documentation
 

docs/migration/guide/automated.md

@@ -1,4 +1,4 @@
-# Migrate Automated Content to V3
+# 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.
 
@@ -15,8 +15,8 @@ Once you have these files, follow the [Contribute Locally guide](../../contribut
 
 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))
+* Custom directives — our main extension point over markdown (learn more [here](../../syntax/index.md))
+* A few GitHub flavored markdown extensions (see the list [here](../../syntax/index.md))
 
 In most cases, plain Markdown covers basic needs, and directives add extra functionality as needed.
 
@@ -43,4 +43,4 @@ 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.
+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/index.md

@@ -1,7 +1,11 @@
 # Migration Guide
 
-Migrate content from Asciidoc to V3
+How do I migrate content? How do I work with migrated content? What's actually moving?
 
-* [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
+_For writers_ --> [**How to work in `elastic/docs-content`**](./working-in-docs-content.md)
+
+_For developers_ --> [**How to migrate automated documentation**](./automated.md)
+
+_For the migration team_ --> [**How to migrate narrative content**](./tooling.md)
+
+_For the generally curious_ --> [**What books were migrated?**](./mapping.md)