Skip to content

Commit deb3bef

Browse files
bmorelli25bmorelli25
committed
start migration guide
1 parent f73df07 commit deb3bef

File tree

4 files changed

+303
-1
lines changed

4 files changed

+303
-1
lines changed

‎docs/source/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,6 @@ Here's my warning
2323
```
2424
````
2525

26-
2726
```javascript
2827
const variable = "hello world";
2928
```
@@ -43,6 +42,7 @@ Read the [quick start guide](https://github.com/elastic/markitpy/tree/main), clo
4342
:hidden:
4443
4544
elastic/index.md
45+
migration/index.md
4646
markup/index.md
4747
nested/index.md
4848
versioning/index.md

‎docs/source/migration/index.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Migration Guide
3+
---
4+
5+
Migration issue: https://github.com/elastic/docs-eng-team/issues/97
6+
7+
Migration guide in progress.
8+
Adapted from the MDX migration guide: https://docs.elastic.dev/migration/syntax.
9+
10+
## Syntax
11+
12+
* [Admonitions](syntax/admonitions.md)
13+
* [Tabs](syntax/tabs.md)
14+
15+
```{toctree}
16+
:hidden:
17+
18+
syntax/admonitions.md
19+
syntax/tabs.md
20+
```

‎docs/source/migration/syntax/admonitions.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
---
2+
title: Admonitions
3+
---
4+
5+
This guide provides instructions for converting common AsciiDoc admonitions to MyST Markdown format.
6+
7+
## Admonition Mapping
8+
9+
| AsciiDoc | MyST Markdown |
10+
|--------------|----------------|
11+
| NOTE | `{note}` |
12+
| TIP | `{tip}` |
13+
| IMPORTANT | `{important}` |
14+
| WARNING | `{warning}` |
15+
| CAUTION | `{caution}` |
16+
| DANGER | `{danger}` |
17+
18+
### Example Conversion
19+
20+
In AsciiDoc:
21+
```text
22+
[NOTE]
23+
====
24+
This is a note.
25+
It can be multiple lines, but not multiple paragraphs.
26+
====
27+
```
28+
29+
In MyST Markdown:
30+
```
31+
:::{note}
32+
This is a note.
33+
It can be multiple lines, but not multiple paragraphs.
34+
:::
35+
```
36+
37+
:::{note}
38+
This is a note.
39+
It can be multiple lines, but not multiple paragraphs.
40+
:::
41+
42+
## Admonition Paragraphs
43+
44+
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.
45+
46+
### Example
47+
48+
In AsciiDoc:
49+
```text
50+
[WARNING]
51+
====
52+
This is a warning paragraph.
53+
====
54+
```
55+
56+
In MyST Markdown:
57+
```
58+
:::{warning}
59+
This is a warning paragraph.
60+
:::
61+
```
62+
63+
:::{warning}
64+
This is a warning paragraph.
65+
:::
66+
67+
## Multi-Paragraph Admonitions
68+
69+
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.
70+
71+
### Example
72+
73+
In AsciiDoc:
74+
```text
75+
[IMPORTANT]
76+
====
77+
This is an important note.
78+
It contains multiple paragraphs.
79+
80+
Make sure to read it carefully.
81+
====
82+
```
83+
84+
In MyST Markdown:
85+
```
86+
:::{important}
87+
This is an important note.
88+
It contains multiple paragraphs.
89+
90+
Make sure to read it carefully.
91+
:::
92+
```
93+
94+
:::{important}
95+
This is an important note.
96+
It contains multiple paragraphs.
97+
98+
Make sure to read it carefully.
99+
:::
100+
101+
## Custom Titles for Admonitions
102+
103+
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.
104+
105+
### Example
106+
107+
In AsciiDoc:
108+
```text
109+
[NOTE]
110+
.Title goes here
111+
====
112+
This note has a custom title.
113+
====
114+
```
115+
116+
In MyST Markdown:
117+
```
118+
:::{admonition} Title goes here
119+
:class: note
120+
121+
This note has a custom title.
122+
:::
123+
```
124+
125+
:::{admonition} Title goes here
126+
:class: note
127+
128+
This note has a custom title.
129+
:::
130+
131+
## Collapsible Admonitions
132+
133+
In MyST Markdown, you can make an admonition collapsible by adding a `dropdown` class, provided by the `sphinx-togglebutton` extension.
134+
135+
### Example
136+
137+
```
138+
:::{note}
139+
:class: dropdown
140+
141+
This admonition can be collapsed, making it useful for longer notes or instructions.
142+
:::
143+
```
144+
145+
:::{note}
146+
:class: dropdown
147+
148+
This admonition can be collapsed, making it useful for longer notes or instructions.
149+
:::

‎docs/source/migration/syntax/tabs.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
---
2+
title: Tabs
3+
---
4+
5+
This guide provides instructions for converting AsciiDoc tabbed widgets to MyST Markdown format.
6+
7+
## Tabbed Widget Mapping
8+
9+
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.
10+
11+
### Example Conversion
12+
13+
In AsciiDoc:
14+
```text
15+
[[tabbed-widgets]]
16+
== Tabbed widgets
17+
18+
Improve the usability of your docs by adding tabbed widgets.
19+
These handy widgets let you conditionally display content based on the selected tab.
20+
21+
**`widget.asciidoc`**
22+
23+
[source,asciidoc]
24+
----
25+
++++
26+
<div class="tabs" data-tab-group="custom-tab-group-name">
27+
<div role="tablist" aria-label="Human readable name of tab group">
28+
<button role="tab" aria-selected="true" aria-controls="cloud-tab-config-agent" id="cloud-config-agent">
29+
Tab #1 title
30+
</button>
31+
<button role="tab" aria-selected="false" aria-controls="self-managed-tab-config-agent" id="self-managed-config-agent" tabindex="-1">
32+
Tab #2 title
33+
</button>
34+
</div>
35+
<div tabindex="0" role="tabpanel" id="cloud-tab-config-agent" aria-labelledby="cloud-config-agent">
36+
++++
37+
38+
// include::content.asciidoc[tag=central-config]
39+
40+
++++
41+
</div>
42+
<div tabindex="0" role="tabpanel" id="self-managed-tab-config-agent" aria-labelledby="self-managed-config-agent" hidden="">
43+
++++
44+
45+
// include::content.asciidoc[tag=reg-config]
46+
47+
++++
48+
</div>
49+
</div>
50+
++++
51+
----
52+
53+
**`content.asciidoc`**
54+
55+
[source,asciidoc]
56+
----
57+
// tag::central-config[]
58+
This is where the content for tab #1 goes.
59+
// end::central-config[]
60+
61+
// tag::reg-config[]
62+
This is where the content for tab #2 goes.
63+
// end::reg-config[]
64+
----
65+
```
66+
67+
In MyST Markdown:
68+
```markdown
69+
::::{tab-set}
70+
71+
:::{tab-item} Tab #1 title
72+
This is where the content for tab #1 goes.
73+
:::
74+
75+
:::{tab-item} Tab #2 title
76+
This is where the content for tab #2 goes.
77+
:::
78+
79+
::::
80+
```
81+
82+
::::{tab-set}
83+
84+
:::{tab-item} Tab #1 title
85+
This is where the content for tab #1 goes.
86+
:::
87+
88+
:::{tab-item} Tab #2 title
89+
This is where the content for tab #2 goes.
90+
:::
91+
92+
::::
93+
94+
## Converting HTML and Passthrough Blocks
95+
96+
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.
97+
98+
### Example
99+
100+
In AsciiDoc:
101+
```text
102+
<div class="tabs" data-tab-group="example-group">
103+
<button role="tab" aria-controls="example-tab1">Tab 1</button>
104+
<button role="tab" aria-controls="example-tab2">Tab 2</button>
105+
</div>
106+
```
107+
108+
In MyST Markdown:
109+
```markdown
110+
::::{tab-set}
111+
112+
:::{tab-item} Tab 1
113+
Content for Tab 1.
114+
:::
115+
116+
:::{tab-item} Tab 2
117+
Content for Tab 2.
118+
:::
119+
120+
::::
121+
```
122+
123+
::::{tab-set}
124+
125+
:::{tab-item} Tab 1
126+
Content for Tab 1.
127+
:::
128+
129+
:::{tab-item} Tab 2
130+
Content for Tab 2.
131+
:::
132+
133+
::::

0 commit comments

Comments
 (0)