start migration guide

docs/source/index.md

@@ -23,7 +23,6 @@ Here's my warning
 ```
 ````
 
-
 ```javascript
 const variable = "hello world";
 ```
@@ -43,6 +42,7 @@ Read the [quick start guide](https://github.com/elastic/markitpy/tree/main), clo
 :hidden:
 
 elastic/index.md
+migration/index.md
 markup/index.md
 nested/index.md
 versioning/index.md

docs/source/migration/index.md

@@ -0,0 +1,20 @@
+---
+title: Migration Guide
+---
+
+Migration issue: https://github.com/elastic/docs-eng-team/issues/97
+
+Migration guide in progress.
+Adapted from the MDX migration guide: https://docs.elastic.dev/migration/syntax.
+
+## Syntax
+
+* [Admonitions](syntax/admonitions.md)
+* [Tabs](syntax/tabs.md)
+
+```{toctree}
+:hidden:
+
+syntax/admonitions.md
+syntax/tabs.md
+```

docs/source/migration/syntax/admonitions.md

@@ -0,0 +1,149 @@
+---
+title: Admonitions
+---
+
+This guide provides instructions for converting common AsciiDoc admonitions to MyST Markdown format.
+
+## Admonition Mapping
+
+| AsciiDoc     | MyST Markdown  |
+|--------------|----------------|
+| NOTE         | `{note}`       |
+| TIP          | `{tip}`        |
+| IMPORTANT    | `{important}`  |
+| WARNING      | `{warning}`    |
+| CAUTION      | `{caution}`    |
+| DANGER       | `{danger}`     |
+
+### Example Conversion
+
+In AsciiDoc:
+```text
+[NOTE]
+====
+This is a note.
+It can be multiple lines, but not multiple paragraphs.
+====
+```
+
+In MyST Markdown:
+```
+:::{note}
+This is a note.
+It can be multiple lines, but not multiple paragraphs.
+:::
+```
+
+:::{note}
+This is a note.
+It can be multiple lines, but not multiple paragraphs.
+:::
+
+## Admonition Paragraphs
+
+For single-paragraph admonitions, convert them directly to MyST admonition syntax using the appropriate admonition type. Use triple colons `:::` to open and close the block.
+
+### Example
+
+In AsciiDoc:
+```text
+[WARNING]
+====
+This is a warning paragraph.
+====
+```
+
+In MyST Markdown:
+```
+:::{warning}
+This is a warning paragraph.
+:::
+```
+
+:::{warning}
+This is a warning paragraph.
+:::
+
+## Multi-Paragraph Admonitions
+
+In AsciiDoc, multi-paragraph admonitions are formatted the same as single paragraphs. In MyST, you can still use the admonition type but separate paragraphs with blank lines.
+
+### Example
+
+In AsciiDoc:
+```text
+[IMPORTANT]
+====
+This is an important note.
+It contains multiple paragraphs.
+
+Make sure to read it carefully.
+====
+```
+
+In MyST Markdown:
+```
+:::{important}
+This is an important note.
+It contains multiple paragraphs.
+
+Make sure to read it carefully.
+:::
+```
+
+:::{important}
+This is an important note.
+It contains multiple paragraphs.
+
+Make sure to read it carefully.
+:::
+
+## Custom Titles for Admonitions
+
+To give an admonition a custom title in MyST, use the `admonition` directive with a `class` attribute. This is useful if you want to style the block as one of the core admonition types but need a custom title.
+
+### Example
+
+In AsciiDoc:
+```text
+[NOTE]
+.Title goes here
+====
+This note has a custom title.
+====
+```
+
+In MyST Markdown:
+```
+:::{admonition} Title goes here
+:class: note
+
+This note has a custom title.
+:::
+```
+
+:::{admonition} Title goes here
+:class: note
+
+This note has a custom title.
+:::
+
+## Collapsible Admonitions
+
+In MyST Markdown, you can make an admonition collapsible by adding a `dropdown` class, provided by the `sphinx-togglebutton` extension.
+
+### Example
+
+```
+:::{note}
+:class: dropdown
+
+This admonition can be collapsed, making it useful for longer notes or instructions.
+:::
+```
+
+:::{note}
+:class: dropdown
+
+This admonition can be collapsed, making it useful for longer notes or instructions.
+:::

docs/source/migration/syntax/tabs.md

@@ -0,0 +1,133 @@
+---
+title: Tabs
+---
+
+This guide provides instructions for converting AsciiDoc tabbed widgets to MyST Markdown format.
+
+## Tabbed Widget Mapping
+
+In AsciiDoc, tabbed widgets are created using HTML passthrough blocks combined with `include::` statements for rendering content within each tab. In MyST Markdown, tabbed content is created using the `tab-set` directive with individual `tab-item` blocks for each tab's content.
+
+### Example Conversion
+
+In AsciiDoc:
+```text
+[[tabbed-widgets]]
+== Tabbed widgets
+
+Improve the usability of your docs by adding tabbed widgets.
+These handy widgets let you conditionally display content based on the selected tab.
+
+**`widget.asciidoc`**
+
+[source,asciidoc]
+----
+++++
+<div class="tabs" data-tab-group="custom-tab-group-name">
+  <div role="tablist" aria-label="Human readable name of tab group">
+    <button role="tab" aria-selected="true" aria-controls="cloud-tab-config-agent" id="cloud-config-agent">
+      Tab #1 title
+    </button>
+    <button role="tab" aria-selected="false" aria-controls="self-managed-tab-config-agent" id="self-managed-config-agent" tabindex="-1">
+      Tab #2 title
+    </button>
+  </div>
+  <div tabindex="0" role="tabpanel" id="cloud-tab-config-agent" aria-labelledby="cloud-config-agent">
+++++
+
+// include::content.asciidoc[tag=central-config]
+
+++++
+  </div>
+  <div tabindex="0" role="tabpanel" id="self-managed-tab-config-agent" aria-labelledby="self-managed-config-agent" hidden="">
+++++
+
+// include::content.asciidoc[tag=reg-config]
+
+++++
+  </div>
+</div>
+++++
+----
+
+**`content.asciidoc`**
+
+[source,asciidoc]
+----
+// tag::central-config[]
+This is where the content for tab #1 goes.
+// end::central-config[]
+
+// tag::reg-config[]
+This is where the content for tab #2 goes.
+// end::reg-config[]
+----
+```
+
+In MyST Markdown:
+```markdown
+::::{tab-set}
+
+:::{tab-item} Tab #1 title
+This is where the content for tab #1 goes.
+:::
+
+:::{tab-item} Tab #2 title
+This is where the content for tab #2 goes.
+:::
+
+::::
+```
+
+::::{tab-set}
+
+:::{tab-item} Tab #1 title
+This is where the content for tab #1 goes.
+:::
+
+:::{tab-item} Tab #2 title
+This is where the content for tab #2 goes.
+:::
+
+::::
+
+## Converting HTML and Passthrough Blocks
+
+In MyST, tabbed widgets don’t require passthrough HTML blocks or custom IDs/attributes for accessibility, as the `tab-set` directive handles all tab behavior. Each `tab-item` block represents a single tab, with its label provided in the directive header.
+
+### Example
+
+In AsciiDoc:
+```text
+<div class="tabs" data-tab-group="example-group">
+  <button role="tab" aria-controls="example-tab1">Tab 1</button>
+  <button role="tab" aria-controls="example-tab2">Tab 2</button>
+</div>
+```
+
+In MyST Markdown:
+```markdown
+::::{tab-set}
+
+:::{tab-item} Tab 1
+Content for Tab 1.
+:::
+
+:::{tab-item} Tab 2
+Content for Tab 2.
+:::
+
+::::
+```
+
+::::{tab-set}
+
+:::{tab-item} Tab 1
+Content for Tab 1.
+:::
+
+:::{tab-item} Tab 2
+Content for Tab 2.
+:::
+
+::::