diff --git a/docs/next/util/unpackText.ts b/docs/next/util/unpackText.ts
new file mode 100644
index 0000000000000..9484a31474138
--- /dev/null
+++ b/docs/next/util/unpackText.ts
@@ -0,0 +1,13 @@
+import React from 'react';
+
+// This utility function is for our Markdoc components.
+// This function unpacks the children of the Button component to avoid the hydration error caused by markdoc wraping blocks with an extra
tag.
+// The conditional logic is to ensure that it works in all cases rather than just the one where the children are wrapped in a
- );
-};
From 7ede58f0348ded25d4a722a5f3cd1661ffe8c05b Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Wed, 1 May 2024 09:54:35 -0600
Subject: [PATCH 19/27] Updating testing zone.
---
.../pages/getting-started/testing-zone.md | 167 ++++++++++++++----
1 file changed, 134 insertions(+), 33 deletions(-)
diff --git a/docs/next/pages/getting-started/testing-zone.md b/docs/next/pages/getting-started/testing-zone.md
index 5b3f4436642b0..8057520f9c00f 100644
--- a/docs/next/pages/getting-started/testing-zone.md
+++ b/docs/next/pages/getting-started/testing-zone.md
@@ -3,9 +3,28 @@ title: The Test Zone
description: Tests for all components and features of markdoc and our custom Markdoc build.
---
-# Headers
+# Header 1
-## Complex Header That You Definitely Want to Use an Anchor Link For {% #complex-header %}
+## Header 2
+
+### Header 3
+
+#### Header 4
+
+##### Header 5
+
+## Regular text
+
+When the wire was despatched he had a cup of tea; over it he told me of a diary kept by Jonathan Harker when abroad, and gave me a typewritten copy of it, as also of Mrs. Harker's diary at Whitby. "Take these," he said, "and study them well. When I have returned you will be master of all the facts, and we can then better enter on our inquisition. Keep them safe, for there is in them much of treasure. You will need all your faith, even you who have had such an experience as that of to-day. What is here told," he laid his hand heavily and gravely on the packet of papers as he spoke, "may be the beginning of the end to you and me and many another; or it may sound the knell of the Un-Dead who walk the earth. Read all, I pray you, with the open mind; and if you can add in any way to the story here told do so, for it is all-important. You have kept diary of all these so strange things; is it not so? Yes! Then we shall go through all these together when we meet." He then made ready for his departure, and shortly after drove off to Liverpool Street. I took my way to Paddington, where I arrived about fifteen minutes before the train came in.
+
+## Complex Header Where You Definitely Want to Use an Anchor Link {% #complex-header %}
+
+```
+## Complex Header Where You Definitely Want to Use an
+Anchor Link {\% #complex-header %}
+```
+
+# Vanilla Markdown Nodes
**Bold**
@@ -13,6 +32,7 @@ _Italic_
[Links](/docs/nodes)
+Vanilla markdown images work, but we should really be using the image tag because it optimizes the images, makes them more accessible, and handles resizing them for us.
Lists
@@ -28,13 +48,67 @@ Lists
Code fences
```
+Markdoc doesn't have syntax highlighting out of the box. We're going to need to add that in. When it get's added in, this python code should be beautifully highlighted.
+
+```python
+import random
+
+def magic_8_ball():
+ responses = [
+ "As I see it, yes.",
+ "Ask again later.",
+ "Better not tell you now.",
+ "Cannot predict now.",
+ "Don’t count on it.",
+ "My reply is no.",
+ "My sources say no.",
+ "Outlook not so good.",
+ "Outlook good.",
+ "Reply hazy, try again.",
+ "Yes – definitely.",
+ "You may rely on it.",
+ "Absolutely not!",
+ "Go for it!",
+ "No way, José!",
+ "Oh, hell no!",
+ "Hell yes!",
+ "Yes, if you believe hard enough.",
+ "No, but that shouldn't stop you.",
+ "Why would you even ask that?"
+ ]
+
+ while True:
+ question = input("Ask the Magic 8 Ball a question (type 'exit' to quit): ")
+ if question.lower() == 'exit':
+ print("Magic 8 Ball has left the chat.")
+ break
+ else:
+ print(random.choice(responses))
+
+if __name__ == "__main__":
+ magic_8_ball()
+
+```
+
+# Custom Markdoc Tags
+We've extended markdown with custom tags that let us make the docs richer and more interactive.
+
## Admonitions
+Two types of admonitions are available. Warnings and notes.
+
+`{% warning %} This is a warning {% /warning %}`
+
{% warning %} This is a warning {% /warning %}
+`{% note %} This is a note {% /note %}`
+
{% note %} This is a note {% /note %}
## Buttons
+Buttons are basically just links that are styled to look neat to the user and work for making links stand out.
+
+We have a few different styles of buttons that all do the same thing.
### Default
@@ -60,29 +134,13 @@ Code fences
{% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %}
-
-{% warning %}
-### Don't format the buttons like this!
-` {% button link="https://dog.ceo/" %}`
-
-`Click Me!`
-
-`{% /button %}`
-
-It causes an odd formatting issue.
-
-{% button link="https://dog.ceo/" %}
-Click Me!
-{% /button %}
-{% /warning %}
-
### Button Container
The main use case I've seen for buttons in the docs is basically setting up multiple styling links in a row. Doing this requires putting buttons into a `ButtonContainer`
{% buttonContainer %} {% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} {% /buttonContainer %}
## Crosses and Checks
-A cross looks like this {% cross /%} and a check looks like this {% check /%}.
+You can invoke a cross with this tag `{% cross /}%` and it looks like this {% cross /%}. You can invoke checks with this tag `{% check /}%` and it looks like this {% check /%}.
Crosses and checks can also be used in lists:
- {% check /%} Completed task
@@ -122,37 +180,80 @@ There are three types of badges:
## Code Reference Links
-{% codeReferenceLink filePath="examples/deploy_ecs" %}{% /codeReferenceLink %}
+Code reference links let you point to a specific file in the codebase. They're useful for linking to examples or reference implementations.
+
+`{% codeReferenceLink filePath="examples/deploy_ecs" /%}`
+
+{% codeReferenceLink filePath="examples/deploy_ecs" /%}
+
+
+You can also add text to the link like this:
+
+`{% codeReferenceLink filePath="examples/deploy_ecs" %}Check out our code on Github.{% /codeReferenceLink %}`
+
+{% codeReferenceLink filePath="examples/deploy_ecs" %}Check out our code on Github.{% /codeReferenceLink %}
## Reference Tables
{% referenceTable %}
{% referenceTableItem propertyName="isolated_agents.enabled" %}
-When enabled, agents are isolated and will not be able to access each
-others' resources. See the
-
-Running multiple agents guide
-
-for more information.
+The cool thing about these tables that will spare people working with them a lot of grief is that they support vanilla markdown and custom tags while the MDX implementation only supported HTML.
+
+They still aren't the best thing to work with, but this is a night and day different from having to keep track of raw HTML while authoring.
{% /referenceTableItem %}
{% referenceTableItem propertyName="Item 2" %}
-If the markdown works, we should be able to see it render here.
-- Lists
-- **Should**
-- *Work*
-- Now
+**Bold**
+
+_Italic_
+
+[Links](/docs/nodes)
+
+Vanilla markdown images work, but we should really be using the image tag because it optimizes the images, makes them more accessible, and handles resizing them for us.
+
+
+Lists
+- Item 1
+- Item 1
+- Item 1
+
+> Quotes
-Do They?
+`Inline code`
-Maybe.
+```
+Code fences
+```
{% /referenceTableItem %}
{% /referenceTable %}
## Article Lists
+Authors can use article lists.
+
+They work like this:
+`{% articleList %}`
+
+ `{% articleListItem title="Software-defined Assets" href="/concepts/assets/software-defined-assets" /%}`
+
+ `{% articleListItem title="Graph-backed Assets" href="/concepts/assets/graph-backed-assets" /%}`
+
+ `{% articleListItem title="Multi-assets" href="/concepts/assets/multi-assets" /%}`
+
+ `{% articleListItem title="Asset jobs" href="/concepts/assets/asset-jobs" /%}`
+
+ `{% articleListItem title="Asset observations" href="/concepts/assets/asset-observations" /%}`
+
+ `{% articleListItem title="Asset selection syntax" href="/concepts/assets/asset-selection-syntax" /%}`
+
+ `{% articleListItem title="Asset checks" href="/concepts/assets/asset-checks" /%}`
+
+ `{% articleListItem title="External assets (Experimental)" href="/concepts/assets/external-assets" /%}`
+
+`{% /articleList %}`
+
{% articleList %}
{% articleListItem title="Software-defined Assets" href="/concepts/assets/software-defined-assets" /%}
{% articleListItem title="Graph-backed Assets" href="/concepts/assets/graph-backed-assets" /%}
From d7701cdc2b6eee1fa6cdc983b1f7f998fbade1b6 Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Wed, 1 May 2024 10:41:06 -0600
Subject: [PATCH 20/27] Removing test zone and adding markdoc-component-docs
---
docs/content/_navigation.json | 5 -
docs/markdoc-component-documentation.md | 263 ++++++++++++++++++
.../pages/getting-started/testing-zone.md | 7 -
3 files changed, 263 insertions(+), 12 deletions(-)
create mode 100644 docs/markdoc-component-documentation.md
diff --git a/docs/content/_navigation.json b/docs/content/_navigation.json
index 21aa85869c2b7..d36804c69340b 100644
--- a/docs/content/_navigation.json
+++ b/docs/content/_navigation.json
@@ -5,11 +5,6 @@
"path": "/getting-started",
"isDefaultOpen": true,
"children": [
- {
- "title": "Testing Zone",
- "path": "/getting-started/testing-zone",
- "nonMdx": true
- },
{
"title": "What's Dagster?",
"path": "/getting-started/what-why-dagster"
diff --git a/docs/markdoc-component-documentation.md b/docs/markdoc-component-documentation.md
new file mode 100644
index 0000000000000..b8acc50b58fcc
--- /dev/null
+++ b/docs/markdoc-component-documentation.md
@@ -0,0 +1,263 @@
+---
+title: Authoring Component Examples
+description: This page shows off what each of the components we're using in our docs looks like.
+---
+
+This page contains examples of all of the native Markdoc node and the custom markdoc tags that we are using in our docs.
+
+To see the rendered version of these tags, move this file into the `next/pages/getting-started` directory, run the local server for the site, and navigate to the `getting-started/markdoc-component-documentation` page in your browser.
+
+# Header 1
+
+## Header 2
+
+### Header 3
+
+#### Header 4
+
+##### Header 5
+
+## Regular text
+
+When the wire was despatched he had a cup of tea; over it he told me of a diary kept by Jonathan Harker when abroad, and gave me a typewritten copy of it, as also of Mrs. Harker's diary at Whitby. "Take these," he said, "and study them well. When I have returned you will be master of all the facts, and we can then better enter on our inquisition. Keep them safe, for there is in them much of treasure. You will need all your faith, even you who have had such an experience as that of to-day. What is here told," he laid his hand heavily and gravely on the packet of papers as he spoke, "may be the beginning of the end to you and me and many another; or it may sound the knell of the Un-Dead who walk the earth. Read all, I pray you, with the open mind; and if you can add in any way to the story here told do so, for it is all-important. You have kept diary of all these so strange things; is it not so? Yes! Then we shall go through all these together when we meet." He then made ready for his departure, and shortly after drove off to Liverpool Street. I took my way to Paddington, where I arrived about fifteen minutes before the train came in.
+
+## Complex Header Where You Definitely Want to Use an Anchor Link {% #complex-header %}
+
+```
+## Complex Header Where You Definitely Want to Use an
+Anchor Link {\% #complex-header %}
+```
+
+# Vanilla Markdown Nodes
+
+**Bold**
+
+_Italic_
+
+[Links](/docs/nodes)
+
+Vanilla markdown images work, but we should really be using the image tag because it optimizes the images, makes them more accessible, and handles resizing them for us.
+
+
+Lists
+- Item 1
+- Item 1
+- Item 1
+
+> Quotes
+
+`Inline code`
+
+```
+Code fences
+```
+
+Markdoc doesn't have syntax highlighting out of the box. We're going to need to add that in. When it get's added in, this python code should be beautifully highlighted.
+
+```python
+import random
+
+def magic_8_ball():
+ responses = [
+ "As I see it, yes.",
+ "Ask again later.",
+ "Better not tell you now.",
+ "Cannot predict now.",
+ "Don’t count on it.",
+ "My reply is no.",
+ "My sources say no.",
+ "Outlook not so good.",
+ "Outlook good.",
+ "Reply hazy, try again.",
+ "Yes – definitely.",
+ "You may rely on it.",
+ "Absolutely not!",
+ "Go for it!",
+ "No way, José!",
+ "Oh, hell no!",
+ "Hell yes!",
+ "Yes, if you believe hard enough.",
+ "No, but that shouldn't stop you.",
+ "Why would you even ask that?"
+ ]
+
+ while True:
+ question = input("Ask the Magic 8 Ball a question (type 'exit' to quit): ")
+ if question.lower() == 'exit':
+ print("Magic 8 Ball has left the chat.")
+ break
+ else:
+ print(random.choice(responses))
+
+if __name__ == "__main__":
+ magic_8_ball()
+
+```
+
+# Custom Markdoc Tags
+We've extended markdown with custom tags that let us make the docs richer and more interactive.
+
+## Admonitions
+
+Two types of admonitions are available. Warnings and notes.
+
+`{% warning %} This is a warning {% /warning %}`
+
+{% warning %} This is a warning {% /warning %}
+
+`{% note %} This is a note {% /note %}`
+
+{% note %} This is a note {% /note %}
+
+## Buttons
+Buttons are basically just links that are styled to look neat to the user and work for making links stand out.
+
+We have a few different styles of buttons that all do the same thing.
+
+### Default
+
+`{% button link="https://dog.ceo/" %} Click Me! {% /button %}`
+
+{% button link="https://dog.ceo/" %} Click Me! {% /button %}
+
+### Primary
+
+`{% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %}`
+
+{% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %}
+
+### Secondary
+
+`{% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %}`
+
+{% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %}
+
+### Blurple
+
+` {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} `
+
+{% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %}
+
+### Button Container
+The main use case I've seen for buttons in the docs is basically setting up multiple styling links in a row. Doing this requires putting buttons into a `ButtonContainer`
+
+{% buttonContainer %} {% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} {% /buttonContainer %}
+
+## Crosses and Checks
+You can invoke a cross with this tag `{% cross /}%` and it looks like this {% cross /%}. You can invoke checks with this tag `{% check /}%` and it looks like this {% check /%}.
+
+Crosses and checks can also be used in lists:
+- {% check /%} Completed task
+- {% cross /%} Incomplete task
+- {% cross /%} Super Incomplete task
+
+You can also put crosses and checks into headers
+
+### This is a header with a check {% check /%}
+Which is pretty neat.
+
+### This is a header with a cross {% cross /%}
+Which is also pretty neat.
+
+## Images
+We've got a tag that handles making sure images are pretty, optimized, and accessible.
+
+`{% image src="/images/some-image.png" width=300 height=200 alt="Text for screenreaders. Usually you want to describe things here." /%}`
+
+
+
+{% image src="/images/concepts/assets/asset-activity-observation.png" width=1758 height=1146 alt="Text go here" /%}
+
+
+## Badges
+
+`{% badge text="Badgey the Badger" /%}` lets you put a custom badge onto the page like this. {% badge text="Badgey the Badger" /%}
+
+### API Status Badges
+We've also got a bunch of badges that you can use to indicate the level of support an API or feature has.
+
+There are three types of badges:
+
+- `{% experimental /%}` {% experimental /%}
+- `{% deprecated /%}` {% deprecated /%}
+- `{% legacy /%}` {% legacy /%}
+
+## Code Reference Links
+
+Code reference links let you point to a specific file in the codebase. They're useful for linking to examples or reference implementations.
+
+`{% codeReferenceLink filePath="examples/deploy_ecs" /%}`
+
+{% codeReferenceLink filePath="examples/deploy_ecs" /%}
+
+## Reference Tables
+
+{% referenceTable %}
+{% referenceTableItem propertyName="isolated_agents.enabled" %}
+The cool thing about these tables that will spare people working with them a lot of grief is that they support vanilla markdown and custom tags while the MDX implementation only supported HTML.
+
+They still aren't the best thing to work with, but this is a night and day different from having to keep track of raw HTML while authoring.
+{% /referenceTableItem %}
+
+{% referenceTableItem propertyName="Item 2" %}
+
+**Bold**
+
+_Italic_
+
+[Links](/docs/nodes)
+
+Vanilla markdown images work, but we should really be using the image tag because it optimizes the images, makes them more accessible, and handles resizing them for us.
+
+
+Lists
+- Item 1
+- Item 1
+- Item 1
+
+> Quotes
+
+`Inline code`
+
+```
+Code fences
+```
+{% /referenceTableItem %}
+
+{% /referenceTable %}
+
+## Article Lists
+
+Authors can use article lists.
+
+They work like this:
+`{% articleList %}`
+
+ `{% articleListItem title="Software-defined Assets" href="/concepts/assets/software-defined-assets" /%}`
+
+ `{% articleListItem title="Graph-backed Assets" href="/concepts/assets/graph-backed-assets" /%}`
+
+ `{% articleListItem title="Multi-assets" href="/concepts/assets/multi-assets" /%}`
+
+ `{% articleListItem title="Asset jobs" href="/concepts/assets/asset-jobs" /%}`
+
+ `{% articleListItem title="Asset observations" href="/concepts/assets/asset-observations" /%}`
+
+ `{% articleListItem title="Asset selection syntax" href="/concepts/assets/asset-selection-syntax" /%}`
+
+ `{% articleListItem title="Asset checks" href="/concepts/assets/asset-checks" /%}`
+
+ `{% articleListItem title="External assets (Experimental)" href="/concepts/assets/external-assets" /%}`
+
+`{% /articleList %}`
+
+{% articleList %}
+ {% articleListItem title="Software-defined Assets" href="/concepts/assets/software-defined-assets" /%}
+ {% articleListItem title="Graph-backed Assets" href="/concepts/assets/graph-backed-assets" /%}
+ {% articleListItem title="Multi-assets" href="/concepts/assets/multi-assets" /%}
+ {% articleListItem title="Asset jobs" href="/concepts/assets/asset-jobs" /%}
+ {% articleListItem title="Asset observations" href="/concepts/assets/asset-observations" /%}
+ {% articleListItem title="Asset selection syntax" href="/concepts/assets/asset-selection-syntax" /%}
+ {% articleListItem title="Asset checks" href="/concepts/assets/asset-checks" /%}
+ {% articleListItem title="External assets (Experimental)" href="/concepts/assets/external-assets" /%}
+{% /articleList %}
diff --git a/docs/next/pages/getting-started/testing-zone.md b/docs/next/pages/getting-started/testing-zone.md
index 8057520f9c00f..09526c446fb5f 100644
--- a/docs/next/pages/getting-started/testing-zone.md
+++ b/docs/next/pages/getting-started/testing-zone.md
@@ -186,13 +186,6 @@ Code reference links let you point to a specific file in the codebase. They're u
{% codeReferenceLink filePath="examples/deploy_ecs" /%}
-
-You can also add text to the link like this:
-
-`{% codeReferenceLink filePath="examples/deploy_ecs" %}Check out our code on Github.{% /codeReferenceLink %}`
-
-{% codeReferenceLink filePath="examples/deploy_ecs" %}Check out our code on Github.{% /codeReferenceLink %}
-
## Reference Tables
{% referenceTable %}
From dc5263a22a950bf86c6f84ead9f9c50f2d77646c Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Wed, 1 May 2024 10:41:35 -0600
Subject: [PATCH 21/27] Deleting testing zone
---
.../pages/getting-started/testing-zone.md | 259 ------------------
1 file changed, 259 deletions(-)
delete mode 100644 docs/next/pages/getting-started/testing-zone.md
diff --git a/docs/next/pages/getting-started/testing-zone.md b/docs/next/pages/getting-started/testing-zone.md
deleted file mode 100644
index 09526c446fb5f..0000000000000
--- a/docs/next/pages/getting-started/testing-zone.md
+++ /dev/null
@@ -1,259 +0,0 @@
----
-title: The Test Zone
-description: Tests for all components and features of markdoc and our custom Markdoc build.
----
-
-# Header 1
-
-## Header 2
-
-### Header 3
-
-#### Header 4
-
-##### Header 5
-
-## Regular text
-
-When the wire was despatched he had a cup of tea; over it he told me of a diary kept by Jonathan Harker when abroad, and gave me a typewritten copy of it, as also of Mrs. Harker's diary at Whitby. "Take these," he said, "and study them well. When I have returned you will be master of all the facts, and we can then better enter on our inquisition. Keep them safe, for there is in them much of treasure. You will need all your faith, even you who have had such an experience as that of to-day. What is here told," he laid his hand heavily and gravely on the packet of papers as he spoke, "may be the beginning of the end to you and me and many another; or it may sound the knell of the Un-Dead who walk the earth. Read all, I pray you, with the open mind; and if you can add in any way to the story here told do so, for it is all-important. You have kept diary of all these so strange things; is it not so? Yes! Then we shall go through all these together when we meet." He then made ready for his departure, and shortly after drove off to Liverpool Street. I took my way to Paddington, where I arrived about fifteen minutes before the train came in.
-
-## Complex Header Where You Definitely Want to Use an Anchor Link {% #complex-header %}
-
-```
-## Complex Header Where You Definitely Want to Use an
-Anchor Link {\% #complex-header %}
-```
-
-# Vanilla Markdown Nodes
-
-**Bold**
-
-_Italic_
-
-[Links](/docs/nodes)
-
-Vanilla markdown images work, but we should really be using the image tag because it optimizes the images, makes them more accessible, and handles resizing them for us.
-
-
-Lists
-- Item 1
-- Item 1
-- Item 1
-
-> Quotes
-
-`Inline code`
-
-```
-Code fences
-```
-
-Markdoc doesn't have syntax highlighting out of the box. We're going to need to add that in. When it get's added in, this python code should be beautifully highlighted.
-
-```python
-import random
-
-def magic_8_ball():
- responses = [
- "As I see it, yes.",
- "Ask again later.",
- "Better not tell you now.",
- "Cannot predict now.",
- "Don’t count on it.",
- "My reply is no.",
- "My sources say no.",
- "Outlook not so good.",
- "Outlook good.",
- "Reply hazy, try again.",
- "Yes – definitely.",
- "You may rely on it.",
- "Absolutely not!",
- "Go for it!",
- "No way, José!",
- "Oh, hell no!",
- "Hell yes!",
- "Yes, if you believe hard enough.",
- "No, but that shouldn't stop you.",
- "Why would you even ask that?"
- ]
-
- while True:
- question = input("Ask the Magic 8 Ball a question (type 'exit' to quit): ")
- if question.lower() == 'exit':
- print("Magic 8 Ball has left the chat.")
- break
- else:
- print(random.choice(responses))
-
-if __name__ == "__main__":
- magic_8_ball()
-
-```
-
-# Custom Markdoc Tags
-We've extended markdown with custom tags that let us make the docs richer and more interactive.
-
-## Admonitions
-
-Two types of admonitions are available. Warnings and notes.
-
-`{% warning %} This is a warning {% /warning %}`
-
-{% warning %} This is a warning {% /warning %}
-
-`{% note %} This is a note {% /note %}`
-
-{% note %} This is a note {% /note %}
-
-## Buttons
-Buttons are basically just links that are styled to look neat to the user and work for making links stand out.
-
-We have a few different styles of buttons that all do the same thing.
-
-### Default
-
-`{% button link="https://dog.ceo/" %} Click Me! {% /button %}`
-
-{% button link="https://dog.ceo/" %} Click Me! {% /button %}
-
-### Primary
-
-`{% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %}`
-
-{% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %}
-
-### Secondary
-
-`{% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %}`
-
-{% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %}
-
-### Blurple
-
-` {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} `
-
-{% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %}
-
-### Button Container
-The main use case I've seen for buttons in the docs is basically setting up multiple styling links in a row. Doing this requires putting buttons into a `ButtonContainer`
-
-{% buttonContainer %} {% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} {% /buttonContainer %}
-
-## Crosses and Checks
-You can invoke a cross with this tag `{% cross /}%` and it looks like this {% cross /%}. You can invoke checks with this tag `{% check /}%` and it looks like this {% check /%}.
-
-Crosses and checks can also be used in lists:
-- {% check /%} Completed task
-- {% cross /%} Incomplete task
-- {% cross /%} Super Incomplete task
-
-You can also put crosses and checks into headers
-
-### This is a header with a check {% check /%}
-Which is pretty neat.
-
-### This is a header with a cross {% cross /%}
-Which is also pretty neat.
-
-## Images
-We've got a tag that handles making sure images are pretty, optimized, and accessible.
-
-`{% image src="/images/some-image.png" width=300 height=200 alt="Text for screenreaders. Usually you want to describe things here." /%}`
-
-
-
-{% image src="/images/concepts/assets/asset-activity-observation.png" width=1758 height=1146 alt="Text go here" /%}
-
-
-## Badges
-
-`{% badge text="Badgey the Badger" /%}` lets you put a custom badge onto the page like this. {% badge text="Badgey the Badger" /%}
-
-### API Status Badges
-We've also got a bunch of badges that you can use to indicate the level of support an API or feature has.
-
-There are three types of badges:
-
-- `{% experimental /%}` {% experimental /%}
-- `{% deprecated /%}` {% deprecated /%}
-- `{% legacy /%}` {% legacy /%}
-
-## Code Reference Links
-
-Code reference links let you point to a specific file in the codebase. They're useful for linking to examples or reference implementations.
-
-`{% codeReferenceLink filePath="examples/deploy_ecs" /%}`
-
-{% codeReferenceLink filePath="examples/deploy_ecs" /%}
-
-## Reference Tables
-
-{% referenceTable %}
-{% referenceTableItem propertyName="isolated_agents.enabled" %}
-The cool thing about these tables that will spare people working with them a lot of grief is that they support vanilla markdown and custom tags while the MDX implementation only supported HTML.
-
-They still aren't the best thing to work with, but this is a night and day different from having to keep track of raw HTML while authoring.
-{% /referenceTableItem %}
-
-{% referenceTableItem propertyName="Item 2" %}
-
-**Bold**
-
-_Italic_
-
-[Links](/docs/nodes)
-
-Vanilla markdown images work, but we should really be using the image tag because it optimizes the images, makes them more accessible, and handles resizing them for us.
-
-
-Lists
-- Item 1
-- Item 1
-- Item 1
-
-> Quotes
-
-`Inline code`
-
-```
-Code fences
-```
-{% /referenceTableItem %}
-
-{% /referenceTable %}
-
-## Article Lists
-
-Authors can use article lists.
-
-They work like this:
-`{% articleList %}`
-
- `{% articleListItem title="Software-defined Assets" href="/concepts/assets/software-defined-assets" /%}`
-
- `{% articleListItem title="Graph-backed Assets" href="/concepts/assets/graph-backed-assets" /%}`
-
- `{% articleListItem title="Multi-assets" href="/concepts/assets/multi-assets" /%}`
-
- `{% articleListItem title="Asset jobs" href="/concepts/assets/asset-jobs" /%}`
-
- `{% articleListItem title="Asset observations" href="/concepts/assets/asset-observations" /%}`
-
- `{% articleListItem title="Asset selection syntax" href="/concepts/assets/asset-selection-syntax" /%}`
-
- `{% articleListItem title="Asset checks" href="/concepts/assets/asset-checks" /%}`
-
- `{% articleListItem title="External assets (Experimental)" href="/concepts/assets/external-assets" /%}`
-
-`{% /articleList %}`
-
-{% articleList %}
- {% articleListItem title="Software-defined Assets" href="/concepts/assets/software-defined-assets" /%}
- {% articleListItem title="Graph-backed Assets" href="/concepts/assets/graph-backed-assets" /%}
- {% articleListItem title="Multi-assets" href="/concepts/assets/multi-assets" /%}
- {% articleListItem title="Asset jobs" href="/concepts/assets/asset-jobs" /%}
- {% articleListItem title="Asset observations" href="/concepts/assets/asset-observations" /%}
- {% articleListItem title="Asset selection syntax" href="/concepts/assets/asset-selection-syntax" /%}
- {% articleListItem title="Asset checks" href="/concepts/assets/asset-checks" /%}
- {% articleListItem title="External assets (Experimental)" href="/concepts/assets/external-assets" /%}
-{% /articleList %}
From a472e482bc6e74edf75c60f5161f343659c6265b Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Thu, 2 May 2024 14:48:21 -0600
Subject: [PATCH 22/27] Fixing runtime error from being passed plaintext
elements.
---
docs/next/util/unpackText.ts | 3 ++-
1 file changed, 2 insertions(+), 1 deletion(-)
diff --git a/docs/next/util/unpackText.ts b/docs/next/util/unpackText.ts
index 9484a31474138..cff36304a4beb 100644
--- a/docs/next/util/unpackText.ts
+++ b/docs/next/util/unpackText.ts
@@ -5,7 +5,8 @@ import React from 'react';
// The conditional logic is to ensure that it works in all cases rather than just the one where the children are wrapped in a
tag.
export const unpackText = (children) => {
- if (children.type === 'p') {
+ console.log(children);
+ if (children?.type === 'p') {
return [...React.Children.toArray(children.props.children)];
} else {
return children;
From 1f8989ca719bb007588ae3fa86baf6307165efc6 Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Thu, 2 May 2024 14:50:06 -0600
Subject: [PATCH 23/27] Moving unpack text to Admonition component instead of
warning or note.
---
docs/next/components/markdoc/Callouts.tsx | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/next/components/markdoc/Callouts.tsx b/docs/next/components/markdoc/Callouts.tsx
index 3f335e2f844f5..c741c66bd81d7 100644
--- a/docs/next/components/markdoc/Callouts.tsx
+++ b/docs/next/components/markdoc/Callouts.tsx
@@ -34,7 +34,7 @@ const Admonition = ({style, children}) => {
- {children}
+ {unpackText(children)}
@@ -42,9 +42,9 @@ const Admonition = ({style, children}) => {
};
export const Note = ({children}) => {
- return {unpackText(children)};
+ return {children};
};
export const Warning = ({children}) => {
- return {unpackText(children)};
+ return {children};
};
From 66be5b597f60af256f4a82a94ceabbcb3d08da2b Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Thu, 2 May 2024 15:10:43 -0600
Subject: [PATCH 24/27] Updating component docs to resolve issue and explain
block and inline tags.
---
docs/markdoc-component-documentation.md | 69 +++++++++++++++++++------
1 file changed, 53 insertions(+), 16 deletions(-)
diff --git a/docs/markdoc-component-documentation.md b/docs/markdoc-component-documentation.md
index b8acc50b58fcc..b3e2d0302c554 100644
--- a/docs/markdoc-component-documentation.md
+++ b/docs/markdoc-component-documentation.md
@@ -97,19 +97,38 @@ if __name__ == "__main__":
# Custom Markdoc Tags
We've extended markdown with custom tags that let us make the docs richer and more interactive.
-## Admonitions
+{% warning %}
+There are two types of tags.
+- Inline tags can be used in the middle of a line of and look like this `{% inlineTag %} Inline tag contents {% /inline tags %}`
+- Block tags can be used to wrap around a block of content and look like this:
+
+`{% blockTag %}`
+
+`Block tag contents`
+
+`{% /blockTag %}`
+
+The docs for each tag calls out whether it can be used inline, as a block, or both.
+
+{% /warning %}
+
+## Admonitions : Block
Two types of admonitions are available. Warnings and notes.
`{% warning %} This is a warning {% /warning %}`
-{% warning %} This is a warning {% /warning %}
+{% warning %}
+This is a warning
+{% /warning %}
`{% note %} This is a note {% /note %}`
-{% note %} This is a note {% /note %}
+{% note %}
+This is a note
+{% /note %}
-## Buttons
+## Button : Block
Buttons are basically just links that are styled to look neat to the user and work for making links stand out.
We have a few different styles of buttons that all do the same thing.
@@ -118,32 +137,50 @@ We have a few different styles of buttons that all do the same thing.
`{% button link="https://dog.ceo/" %} Click Me! {% /button %}`
-{% button link="https://dog.ceo/" %} Click Me! {% /button %}
+{% button link="https://dog.ceo/" %}
+Click Me!
+{% /button %}
### Primary
`{% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %}`
-{% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %}
+{% button link="https://dog.ceo/" style="primary" %}
+Click Me!
+{% /button %}
### Secondary
`{% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %}`
-{% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %}
+{% button link="https://dog.ceo/" style="secondary" %}
+Click Me!
+{% /button %}
### Blurple
` {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} `
-{% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %}
+{% button link="https://dog.ceo/" style="blurple" %}
+Click Me!
+{% /button %}
-### Button Container
+### Button Container : Block
The main use case I've seen for buttons in the docs is basically setting up multiple styling links in a row. Doing this requires putting buttons into a `ButtonContainer`
-{% buttonContainer %} {% button link="https://dog.ceo/" style="primary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="secondary" %} Click Me! {% /button %} {% button link="https://dog.ceo/" style="blurple" %} Click Me! {% /button %} {% /buttonContainer %}
-
-## Crosses and Checks
+{% buttonContainer %}
+{% button link="https://dog.ceo/" style="primary" %}
+Click Me!
+{% /button %}
+{% button link="https://dog.ceo/" style="secondary" %}
+Click Me!
+{% /button %}
+{% button link="https://dog.ceo/" style="blurple" %}
+Click Me!
+{% /button %}
+{% /buttonContainer %}
+
+## Crosses and Checks : Inline
You can invoke a cross with this tag `{% cross /}%` and it looks like this {% cross /%}. You can invoke checks with this tag `{% check /}%` and it looks like this {% check /%}.
Crosses and checks can also be used in lists:
@@ -169,7 +206,7 @@ We've got a tag that handles making sure images are pretty, optimized, and acces
{% image src="/images/concepts/assets/asset-activity-observation.png" width=1758 height=1146 alt="Text go here" /%}
-## Badges
+## Badges : Inline
`{% badge text="Badgey the Badger" /%}` lets you put a custom badge onto the page like this. {% badge text="Badgey the Badger" /%}
@@ -182,7 +219,7 @@ There are three types of badges:
- `{% deprecated /%}` {% deprecated /%}
- `{% legacy /%}` {% legacy /%}
-## Code Reference Links
+## Code Reference Links : Block
Code reference links let you point to a specific file in the codebase. They're useful for linking to examples or reference implementations.
@@ -190,7 +227,7 @@ Code reference links let you point to a specific file in the codebase. They're u
{% codeReferenceLink filePath="examples/deploy_ecs" /%}
-## Reference Tables
+## Reference Tables : Block
{% referenceTable %}
{% referenceTableItem propertyName="isolated_agents.enabled" %}
@@ -226,7 +263,7 @@ Code fences
{% /referenceTable %}
-## Article Lists
+## Article Lists : Block
Authors can use article lists.
From 41e3766650b9809f03a2f765942764cc7af01c00 Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Thu, 9 May 2024 10:01:52 -0600
Subject: [PATCH 25/27] Updating Callouts to resolve following defects found in
testing. - Icon does not start at top of the page with text.
Markdoc changes the order that CSS classes get applied to child elements compared to preexisting MDX approach so some changes are required to make sure the child elements style correctly.
- Child text does not receive colors.text style for some element types.
- Child text does not receive text-sm class in some cases.
The function applyTextStyles addresses this.
---
docs/next/components/markdoc/Callouts.tsx | 22 ++++++++++++++++------
docs/next/styles/globals.css | 10 ++++++++++
docs/next/util/unpackText.ts | 2 +-
3 files changed, 27 insertions(+), 7 deletions(-)
diff --git a/docs/next/components/markdoc/Callouts.tsx b/docs/next/components/markdoc/Callouts.tsx
index c741c66bd81d7..98f3e9a67da77 100644
--- a/docs/next/components/markdoc/Callouts.tsx
+++ b/docs/next/components/markdoc/Callouts.tsx
@@ -1,5 +1,4 @@
-import {unpackText} from 'util/unpackText';
-// import * as React from 'react';
+import * as React from 'react';
import Icons from '../Icons';
@@ -17,14 +16,25 @@ const ADMONITION_STYLES = {
icon: Icons.About,
},
};
+
+const applyTextStyles = (children, colors) => {
+ return React.Children.map(children, (child) => {
+ const existingStyles = child.props.className || '';
+ const newStyles = `text-sm text-${colors.text} ${existingStyles}`;
+ return React.cloneElement(child, {className: newStyles});
+ });
+};
+
const Admonition = ({style, children}) => {
const {colors, icon} = ADMONITION_STYLES[style];
+ console.log(children);
return (
-
+
+ {/* Make container for the svg element that aligns it with the top right of the parent flex container */}
-
- {unpackText(children)}
+
+
{applyTextStyles(children, colors)}
diff --git a/docs/next/styles/globals.css b/docs/next/styles/globals.css
index 07dfd87ffab3b..b7aee0dd3507f 100644
--- a/docs/next/styles/globals.css
+++ b/docs/next/styles/globals.css
@@ -608,3 +608,13 @@ dl, dl * {
td {
word-break:break-word
}
+
+/* These classes make sure the .prose p margins don't make the admonition look bad. */
+
+.admonition > :first-child {
+ margin-top: 0;
+}
+
+.admonition > :last-child {
+ margin-bottom: 0;
+}
diff --git a/docs/next/util/unpackText.ts b/docs/next/util/unpackText.ts
index cff36304a4beb..53fc4bc3aad47 100644
--- a/docs/next/util/unpackText.ts
+++ b/docs/next/util/unpackText.ts
@@ -5,7 +5,7 @@ import React from 'react';
// The conditional logic is to ensure that it works in all cases rather than just the one where the children are wrapped in a
tag.
export const unpackText = (children) => {
- console.log(children);
+ // console.log(children);
if (children?.type === 'p') {
return [...React.Children.toArray(children.props.children)];
} else {
From 8486b9044abbac578d74d0e4776863ef8516baad Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Wed, 15 May 2024 10:47:40 -0600
Subject: [PATCH 26/27] Revert "Connecting Link ndoe to NextJS's Next Link
component"
This reverts commit 01203f40804be1cd6d5c494065850f09da019d78.
On branch docs/mdx-component-to-markdoc
Your branch is up to date with 'origin/docs/mdx-component-to-markdoc'.
Changes to be committed:
modified: docs/next/markdoc/nodes/index.ts
deleted: docs/next/markdoc/nodes/link.markdoc.ts
Reverting this commit to have it be a separate pull request for easier reviewing.
---
docs/next/markdoc/nodes/index.ts | 1 -
docs/next/markdoc/nodes/link.markdoc.ts | 10 ----------
2 files changed, 11 deletions(-)
delete mode 100644 docs/next/markdoc/nodes/link.markdoc.ts
diff --git a/docs/next/markdoc/nodes/index.ts b/docs/next/markdoc/nodes/index.ts
index 3ced937a1c414..0553cb942c29a 100644
--- a/docs/next/markdoc/nodes/index.ts
+++ b/docs/next/markdoc/nodes/index.ts
@@ -1,3 +1,2 @@
/* Use this file to export your markdoc nodes */
export * from './heading.markdoc';
-export * from './link.markdoc';
diff --git a/docs/next/markdoc/nodes/link.markdoc.ts b/docs/next/markdoc/nodes/link.markdoc.ts
deleted file mode 100644
index 4857248503f38..0000000000000
--- a/docs/next/markdoc/nodes/link.markdoc.ts
+++ /dev/null
@@ -1,10 +0,0 @@
-import Link from 'next/link';
-
-export const link = {
- render: Link,
- attributes: {
- href: {
- type: String,
- },
- },
-};
From 537c67e1bce23c643305304b85257e4c98e0aaab Mon Sep 17 00:00:00 2001
From: Niko <39569270+nikomancy@users.noreply.github.com>
Date: Wed, 22 May 2024 10:31:26 -0600
Subject: [PATCH 27/27] Fixing issues caused by MDX and Markdoc using the same
components.
---
docs/next/components/markdoc/Callouts.tsx | 1 -
docs/next/components/mdx/MDXComponents.tsx | 55 +++++++++++++++++++++-
2 files changed, 54 insertions(+), 2 deletions(-)
diff --git a/docs/next/components/markdoc/Callouts.tsx b/docs/next/components/markdoc/Callouts.tsx
index 98f3e9a67da77..f042de67aca6c 100644
--- a/docs/next/components/markdoc/Callouts.tsx
+++ b/docs/next/components/markdoc/Callouts.tsx
@@ -27,7 +27,6 @@ const applyTextStyles = (children, colors) => {
const Admonition = ({style, children}) => {
const {colors, icon} = ADMONITION_STYLES[style];
- console.log(children);
return (