diff --git a/docs/content/dagster-plus/deployment/agents/amazon-ecs/configuration-reference.mdx b/docs/content/dagster-plus/deployment/agents/amazon-ecs/configuration-reference.mdx index 67e6eb188dfb8..39bad9ed1f086 100644 --- a/docs/content/dagster-plus/deployment/agents/amazon-ecs/configuration-reference.mdx +++ b/docs/content/dagster-plus/deployment/agents/amazon-ecs/configuration-reference.mdx @@ -309,7 +309,7 @@ agent_queues: - Optional arn of the secret to authenticate into your private container registry. This does not apply if you are leveraging ECR for your images, see https://docs.aws.amazon.com/AmazonECS/latest/userguide/private-auth.html. + Optional arn of the secret to authenticate into your private container registry. This does not apply if you are leveraging ECR for your images, see the AWS private auth guide. diff --git a/docs/markdoc-component-documentation.md b/docs/markdoc-component-documentation.md new file mode 100644 index 0000000000000..b3e2d0302c554 --- /dev/null +++ b/docs/markdoc-component-documentation.md @@ -0,0 +1,300 @@ +--- +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. +![Images](/images/concepts/assets/asset-activity-observation.png) + +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. + +{% 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 %} + +`{% note %} This is a note {% /note %}` + +{% note %} +This is a note +{% /note %} + +## 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. + +### 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 : 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 : 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: +- {% 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 : Inline + +`{% 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 : Block + +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 : Block + +{% 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. +![Images](/images/concepts/assets/asset-activity-observation.png) + +Lists +- Item 1 +- Item 1 +- Item 1 + +> Quotes + +`Inline code` + +``` +Code fences +``` +{% /referenceTableItem %} + +{% /referenceTable %} + +## Article Lists : Block + +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/components/markdoc/ArticleList.tsx b/docs/next/components/markdoc/ArticleList.tsx new file mode 100644 index 0000000000000..0127a710c81f3 --- /dev/null +++ b/docs/next/components/markdoc/ArticleList.tsx @@ -0,0 +1,42 @@ +import {unpackText} from 'util/unpackText'; + +import NextLink from 'next/link'; + +import Link from '../Link'; + +export const ArticleList = ({children}) => { + return ( +
+
+ +
+
+ ); +}; + +export const ArticleListItem = ({title, href}) => { + return ( +
  • + {href.startsWith('http') ? ( + + {title} + + ) : ( + {title} + )} +
    • + ); +}; diff --git a/docs/next/components/markdoc/Badges.tsx b/docs/next/components/markdoc/Badges.tsx new file mode 100644 index 0000000000000..c8b314ef2f55c --- /dev/null +++ b/docs/next/components/markdoc/Badges.tsx @@ -0,0 +1,36 @@ +import {getColorForString} from '../../util/getColorForString'; + +export const Badge = ({text}) => { + const colors = getColorForString(text); + return ( + + {text} + + ); +}; + +export const Experimental = () => { + return ( +
    + (Experimental) +
    + ); +}; + +export const Deprecated = () => { + return ( +
    + (Deprecated) +
    + ); +}; + +export const Legacy = () => { + return ( +
    + (Legacy) +
    + ); +}; diff --git a/docs/next/components/markdoc/Button.tsx b/docs/next/components/markdoc/Button.tsx new file mode 100644 index 0000000000000..0f6bb51776369 --- /dev/null +++ b/docs/next/components/markdoc/Button.tsx @@ -0,0 +1,40 @@ +import {unpackText} from 'util/unpackText'; + +import cx from 'classnames'; +import * as React from 'react'; + +export const ButtonContainer = ({children}: {children: any}) => { + const buttons = React.Children.toArray(children); + return ( +
    + {...buttons} +
    + ); +}; + +export const Button = ({ + link, + style = 'primary', + children, +}: { + children: any; + link: string; + style?: 'primary' | 'secondary' | 'blurple'; +}) => { + return ( +
    + + {unpackText(children)} + +
    + ); +}; diff --git a/docs/next/components/markdoc/Callouts.tsx b/docs/next/components/markdoc/Callouts.tsx index b2b33d1b1015f..f042de67aca6c 100644 --- a/docs/next/components/markdoc/Callouts.tsx +++ b/docs/next/components/markdoc/Callouts.tsx @@ -1,4 +1,4 @@ -// import * as React from 'react'; +import * as React from 'react'; import Icons from '../Icons'; @@ -16,14 +16,24 @@ 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]; return (
    -
    +
    + {/* Make container for the svg element that aligns it with the top right of the parent flex container */}
    { {icon && icon}
    -
    - {children} +
    +
    {applyTextStyles(children, colors)}
    diff --git a/docs/next/components/markdoc/CheckCross.tsx b/docs/next/components/markdoc/CheckCross.tsx new file mode 100644 index 0000000000000..37b53ac1fdca1 --- /dev/null +++ b/docs/next/components/markdoc/CheckCross.tsx @@ -0,0 +1,33 @@ +export const Check = () => { + return ( + + + + ); +}; + +export const Cross = () => { + return ( + + + + ); +}; diff --git a/docs/next/components/markdoc/CodeReferenceLink.tsx b/docs/next/components/markdoc/CodeReferenceLink.tsx new file mode 100644 index 0000000000000..43317855278ed --- /dev/null +++ b/docs/next/components/markdoc/CodeReferenceLink.tsx @@ -0,0 +1,25 @@ +import {unpackText} from 'util/unpackText'; +import {LATEST_VERSION} from 'util/version'; + +import React from 'react'; + +export const CodeReferenceLink = ({filePath, isInline, children}) => { + const url = `https://github.com/dagster-io/dagster/tree/${LATEST_VERSION}/${filePath}`; + + if (isInline) { + return {unpackText(children)}; + } else { + return ( +
    +
    + + + +
    +
    + You can find the code for this example on Github +
    +
    + ); + } +}; diff --git a/docs/next/components/markdoc/Image.tsx b/docs/next/components/markdoc/Image.tsx new file mode 100644 index 0000000000000..2b6f7c8923825 --- /dev/null +++ b/docs/next/components/markdoc/Image.tsx @@ -0,0 +1,25 @@ +import NextImage from 'next/image'; +import Zoom from 'react-medium-image-zoom'; + +export const Image = ({children, ...props}) => { + /* Only version images when all conditions meet: + * - use component in mdx + * - on non-master version + * - in public/images/ dir + */ + const {src} = props; + if (!src.startsWith('/images/')) { + return ( + + + + ); + } + return ( + + + + + + ); +}; diff --git a/docs/next/components/markdoc/ReferenceTable.tsx b/docs/next/components/markdoc/ReferenceTable.tsx new file mode 100644 index 0000000000000..d9482aa91ab16 --- /dev/null +++ b/docs/next/components/markdoc/ReferenceTable.tsx @@ -0,0 +1,37 @@ +import {unpackText} from 'util/unpackText'; + +import React from 'react'; + +export const ReferenceTable = ({children}) => { + return ( + + + + + + + + {children} +
    PropertyDescription
    + ); +}; + +export const ReferenceTableItem = ({propertyName, children}) => { + return ( + + + {propertyName} + + {unpackText(children)} + + ); +}; diff --git a/docs/next/components/mdx/MDXComponents.tsx b/docs/next/components/mdx/MDXComponents.tsx index 2d206a9840ed4..1f591e618604b 100644 --- a/docs/next/components/mdx/MDXComponents.tsx +++ b/docs/next/components/mdx/MDXComponents.tsx @@ -16,7 +16,7 @@ import Zoom from 'react-medium-image-zoom'; import Icons from '../Icons'; import Link from '../Link'; -import {Note, Warning} from '../markdoc/Callouts'; +// import {Note, Warning} from '../markdoc/Callouts'; import 'react-medium-image-zoom/dist/styles.css'; import {RenderedDAG} from './RenderedDAG'; @@ -129,6 +129,59 @@ const PyObject: React.FunctionComponent<{ ); }; +//////////////////////// +// Callouts // +/////////////////////// + +const ADMONITION_STYLES = { + note: { + colors: { + bg: 'primary-100', + borderIcon: 'primary-500', + text: 'gray-900', + }, + icon: Icons.About, + }, + warning: { + colors: {bg: 'yellow-50', borderIcon: 'yellow-400', text: 'yellow-700'}, + icon: Icons.About, + }, +}; + +const Admonition = ({style, children}) => { + const {colors, icon} = ADMONITION_STYLES[style]; + return ( +
    +
    + {/* Make container for the svg element that aligns it with the top right of the parent flex container */} +
    + +
    +
    +
    {children}
    +
    +
    +
    + ); +}; + +export const Note = ({children}) => { + return {children}; +}; + +export const Warning = ({children}) => { + return {children}; +}; + + ////////////////////// // CHECK // ////////////////////// diff --git a/docs/next/markdoc/config.js b/docs/next/markdoc/config.js new file mode 100644 index 0000000000000..e69de29bb2d1d 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, - }, - }, -}; diff --git a/docs/next/markdoc/tags.js b/docs/next/markdoc/tags.js index 4bc328dddbf66..c966c6226132b 100644 --- a/docs/next/markdoc/tags.js +++ b/docs/next/markdoc/tags.js @@ -1,4 +1,11 @@ +import {ArticleList, ArticleListItem} from '../components/markdoc/ArticleList'; +import {Badge, Experimental, Deprecated, Legacy} from '../components/markdoc/Badges'; +import {Button, ButtonContainer} from '../components/markdoc/Button'; import {Note, Warning} from '../components/markdoc/Callouts'; +import {Check, Cross} from '../components/markdoc/CheckCross'; +import {CodeReferenceLink} from '../components/markdoc/CodeReferenceLink'; +import {Image} from '../components/markdoc/Image'; +import {ReferenceTable, ReferenceTableItem} from '../components/markdoc/ReferenceTable'; export const note = { render: Note, @@ -7,3 +14,121 @@ export const note = { export const warning = { render: Warning, }; + +export const buttonContainer = { + render: ButtonContainer, +}; + +export const button = { + render: Button, + children: ['text'], + attributes: { + link: { + type: String, + }, + style: { + type: String, + default: 'primary', + matches: ['primary', 'secondary', 'blurple'], + }, + }, +}; + +export const check = { + render: Check, + selfClosing: true, +}; + +export const cross = { + render: Cross, + selfClosing: true, +}; + +export const image = { + render: Image, + selfClosing: true, + attributes: { + src: { + type: String, + }, + alt: { + type: String, + }, + width: { + type: Number, + }, + height: { + type: Number, + }, + }, +}; + +export const badge = { + render: Badge, + selfClosing: true, + children: ['text'], + attributes: { + text: { + type: String, + }, + }, +}; + +export const experimental = { + render: Experimental, + selfClosing: true, +}; + +export const deprecated = { + render: Deprecated, + selfClosing: true, +}; + +export const legacy = { + render: Legacy, + selfClosing: true, +}; + +export const codeReferenceLink = { + render: CodeReferenceLink, + children: ['text'], + attributes: { + filePath: { + type: String, + }, + isInline: { + type: Boolean, + default: false, + }, + }, +}; + +export const referenceTable = { + render: ReferenceTable, +}; + +export const referenceTableItem = { + render: ReferenceTableItem, + attributes: { + propertyName: { + type: String, + }, + }, +}; + +export const articleList = { + render: ArticleList, +}; + +export const articleListItem = { + render: ArticleListItem, + selfClosing: true, + attributes: { + title: { + type: String, + }, + href: { + type: String, + }, + }, +}; diff --git a/docs/next/styles/globals.css b/docs/next/styles/globals.css index c07937b1e00e0..b7aee0dd3507f 100644 --- a/docs/next/styles/globals.css +++ b/docs/next/styles/globals.css @@ -589,7 +589,6 @@ pre[class="noop"] { border-radius: 0 !important; } - .n { font-weight: 700; } @@ -604,4 +603,18 @@ pre[class="noop"] { dl, dl * { overflow-wrap: break-word; -} \ No newline at end of file +} + +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/getColorForString.ts b/docs/next/util/getColorForString.ts new file mode 100644 index 0000000000000..2629d4ea412db --- /dev/null +++ b/docs/next/util/getColorForString.ts @@ -0,0 +1,20 @@ +function hashCode(str) { + return str + .split('') + .reduce((prevHash, currVal) => ((prevHash << 5) - prevHash + currVal.charCodeAt(0)) | 0, 0); +} + +export const getColorForString = (s: string) => { + const colors = [ + ['bg-yellow-100 text-yellow-800'], + ['bg-green-100 text-green-800'], + ['bg-blue-100 text-blue-800'], + ['bg-red-100 text-red-800'], + ['bg-indigo-100 text-indigo-800'], + ['bg-pink-100 text-pink-800'], + ['bg-purple-100 text-purple-800'], + ['bg-gray-100 text-gray-800'], + ]; + + return colors[Math.abs(hashCode(s)) % colors.length]; +}; diff --git a/docs/next/util/unpackText.ts b/docs/next/util/unpackText.ts new file mode 100644 index 0000000000000..53fc4bc3aad47 --- /dev/null +++ b/docs/next/util/unpackText.ts @@ -0,0 +1,14 @@ +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

    tag. + +export const unpackText = (children) => { + // console.log(children); + if (children?.type === 'p') { + return [...React.Children.toArray(children.props.children)]; + } else { + return children; + } +};