Website Markdown cleanup (#5485)

.docker/website/dockerfile

@@ -1,3 +1,8 @@
 # syntax=docker/dockerfile:1
 FROM nginx:alpine
+
+RUN rm /etc/nginx/conf.d/default.conf
+
+COPY ./website/config/conf.d /etc/nginx/conf.d
+
 COPY ./website/public /usr/share/nginx/html

cSpell.json

@@ -31,7 +31,8 @@
     "struct",
     "Swashbuckle",
     "traversion",
-    "Websockets"
+    "Websockets",
+    "Newtonsoft"
   ],
   "ignoreWords": [
     "Specwise",
@@ -56,7 +57,7 @@
     "relayjs",
     "Rgba",
     "Postgraphile",
-    "Normen",
+    "Normen"
   ],
   "ignoreRegExpList": [
     "\\((.*)\\)", // Markdown links

website/config/conf.d/default.conf

@@ -0,0 +1,10 @@
+server {
+    listen 80;
+    root /usr/share/nginx/html;
+
+    error_page 404 /404;
+
+    location / {
+        try_files $uri $uri/ =404;
+    }
+}

website/src/components/layout/layout.tsx

@@ -1,7 +1,10 @@
 import { MDXProvider } from "@mdx-js/react";
 import React, { FC } from "react";
+import { BlockQuote } from "../mdx/block-quote";
 import { CodeBlock } from "../mdx/code-block";
+import { Annotation, Code, ExampleTabs, Schema } from "../mdx/example-tabs";
 import { InlineCode } from "../mdx/inline-code";
+import { PackageInstallation } from "../mdx/package-installation";
 import { CookieConsent } from "../misc/cookie-consent";
 import { GlobalStyle } from "../misc/global-style";
 import { Header } from "./header";
@@ -11,6 +14,12 @@ export const Layout: FC = ({ children }) => {
   const components = {
     pre: CodeBlock,
     inlineCode: InlineCode,
+    blockquote: BlockQuote,
+    ExampleTabs,
+    Annotation,
+    Code,
+    Schema,
+    PackageInstallation,
   };
 
   return (

website/src/components/mdx/block-quote.tsx

@@ -0,0 +1,59 @@
+import React, { Children, FC, ReactElement } from "react";
+import { Warning } from "./warning";
+
+const warningText = "Warning: ";
+
+export const BlockQuote: FC = ({ children }) => {
+  const childArray = Children.toArray(children);
+
+  const isWarning =
+    childArray.length > 0 &&
+    React.isValidElement(childArray[0]) &&
+    ((typeof childArray[0].props["children"] === "string" &&
+      childArray[0].props["children"].startsWith(warningText)) ||
+      (Array.isArray(childArray[0].props["children"]) &&
+        childArray[0].props["children"].length > 0 &&
+        typeof childArray[0].props["children"][0] === "string" &&
+        childArray[0].props["children"][0].startsWith(warningText)));
+
+  if (isWarning) {
+    const elements = childArray.filter((child) =>
+      React.isValidElement(child)
+    ) as ReactElement[];
+    const texts = elements.map((elem) => {
+      const innerChildren = elem.props["children"];
+
+      if (
+        typeof innerChildren === "string" &&
+        innerChildren.startsWith(warningText)
+      ) {
+        return innerChildren.substring(warningText.length);
+      }
+
+      if (
+        Array.isArray(innerChildren) &&
+        typeof innerChildren[0] === "string"
+      ) {
+        return innerChildren.map((child) => {
+          if (typeof child === "string" && child.startsWith(warningText)) {
+            return child.substring(warningText.length);
+          }
+
+          return child;
+        });
+      }
+
+      return innerChildren;
+    });
+
+    return (
+      <Warning>
+        {texts.map((text, index) => (
+          <p key={index}>{text}</p>
+        ))}
+      </Warning>
+    );
+  }
+
+  return <blockquote>{children}</blockquote>;
+};

website/src/components/mdx/code-block.tsx

@@ -7,16 +7,19 @@ import { Copy } from "./copy";
 
 export interface CodeBlockProps {
   readonly children: any;
+  readonly language?: Language;
 }
 
-export const CodeBlock: FC<CodeBlockProps> = ({ children }) => {
-  const language = children.props.className.replace(
-    /language-/,
-    ""
-  ) as Language;
-  const meta = children.props.metastring;
+export const CodeBlock: FC<CodeBlockProps> = ({
+  children,
+  language: fallbackLanguage,
+}) => {
+  const language =
+    (children.props?.className?.replace(/language-/, "") as Language) ||
+    fallbackLanguage;
+  const meta = children.props?.metastring;
   const shouldHighlightLine = calculateLinesToHighlight(meta);
-  const code = children.props.children;
+  const code = children.props?.children || children;
 
   return (
     <Container className={`gatsby-highlight code-${language}`}>

website/src/components/mdx/package-installation.tsx

@@ -0,0 +1,51 @@
+import React, { FC } from "react";
+import { CodeBlock } from "./code-block";
+import { InlineCode } from "./inline-code";
+import { InputChoiceTabs } from "./input-choice-tabs";
+import { Warning } from "./warning";
+
+type Props = {
+  readonly packageName: string;
+  readonly external?: boolean;
+};
+
+export const PackageInstallation: FC<Props> = ({ packageName, external }) => {
+  return (
+    <>
+      <InputChoiceTabs>
+        <InputChoiceTabs.CLI>
+          <CodeBlock
+            language="bash"
+            children={`dotnet add package ${packageName}`}
+          />
+        </InputChoiceTabs.CLI>
+
+        <InputChoiceTabs.VisualStudio>
+          <InputChoiceTabs.VisualStudio>
+            <p>
+              Add the <InlineCode>{packageName}</InlineCode> package using the
+              NuGet Package Manager within Visual Studio.
+            </p>
+
+            <p>
+              <a
+                href="https://docs.microsoft.com/nuget/quickstart/install-and-use-a-package-in-visual-studio#nuget-package-manager"
+                target="_blank"
+              >
+                Learn how you can use the NuGet Package Manager to install a
+                package
+              </a>
+            </p>
+          </InputChoiceTabs.VisualStudio>
+        </InputChoiceTabs.VisualStudio>
+      </InputChoiceTabs>
+
+      {!external && (
+        <Warning>
+          All <InlineCode>HotChocolate.*</InlineCode> packages need to have the
+          same version.
+        </Warning>
+      )}
+    </>
+  );
+};

website/src/components/mdx/warning.tsx

@@ -0,0 +1,79 @@
+import React, { FC, ReactNode } from "react";
+import styled from "styled-components";
+import { THEME_COLORS } from "../../shared-style";
+
+type Props = {
+  readonly children: ReactNode;
+};
+
+export const Warning: FC<Props> = ({ children }) => {
+  return (
+    <Container>
+      <Heading>
+        {warningIcon} <span>Warning</span>
+      </Heading>
+
+      {children}
+    </Container>
+  );
+};
+
+const warningIcon = (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    width="16"
+    height="16"
+    viewBox="0 0 16 16"
+  >
+    <path d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z" />
+  </svg>
+);
+
+const Heading = styled.div`
+  fill: ${THEME_COLORS.textContrast};
+  display: flex;
+  align-items: center;
+  gap: 10px;
+
+  > span {
+    margin-bottom: 3px;
+
+    font-weight: bold;
+    line-height: normal;
+  }
+
+  > svg {
+    margin-left: 4px;
+    transform: scale(1.3);
+  }
+`;
+
+const Container = styled.div`
+  padding: 20px 20px;
+  background-color: ${THEME_COLORS.warning};
+  color: ${THEME_COLORS.textContrast};
+  line-height: 1.4;
+
+  @media only screen and (min-width: 860px) {
+    padding: 20px 50px;
+  }
+
+  br {
+    margin-bottom: 16px;
+  }
+
+  a {
+    color: white !important;
+    font-weight: bold;
+    text-decoration: underline;
+  }
+
+  code {
+    border-color: ${THEME_COLORS.textContrast};
+    color: ${THEME_COLORS.textContrast};
+  }
+
+  > p:last-child {
+    margin-bottom: 0;
+  }
+`;

website/src/docs/hotchocolate/v10/advanced/index.md

@@ -10,9 +10,7 @@ If you want to build GraphQL tooling for .NET or your own type system and query-
 
 In order to use the parser, install the following package:
 
-```bash
-dotnet add package HotChocolate.Language
-```
+<PackageInstallation packageName="HotChocolate.Language" />
 
 In order to parse a GraphQL schema or query use it like the following:
 

website/src/docs/hotchocolate/v10/data-fetching/filters.md

@@ -65,7 +65,7 @@ public class Query
 }
 ```
 
-> ⚠️ **Note**: Be sure to install the `HotChocolate.Types.Filters` NuGet package.
+> Warning: Be sure to install the `HotChocolate.Types.Filters` NuGet package.
 
 In the above example the person resolver just returns the `IQueryable` representing the data source. The `IQueryable` represents a not executed database query on which we are able to apply filters.
 
@@ -191,7 +191,7 @@ query {
 }
 ```
 
-> ⚠️ **Note**: Be sure to install the `HotChocolate.Types.Sorting` NuGet package.
+> Warning: Be sure to install the `HotChocolate.Types.Sorting` NuGet package.
 
 If you want to combine for instance paging, filtering and sorting make sure that the order is like follows:
 

website/src/docs/hotchocolate/v10/schema/descriptor-attributes.md

@@ -51,7 +51,7 @@ public class Query
 }
 ```
 
-> ⚠️ **Note**: Be sure to install the `HotChocolate.Types.Filters` NuGet package.
+> Warning: Be sure to install the `HotChocolate.Types.Filters` NuGet package.
 
 ## UseSortingAttribute
 
@@ -68,7 +68,7 @@ public class Query
 }
 ```
 
-> ⚠️ **Note**: Be sure to install the `HotChocolate.Types.Sorting` NuGet package.
+> Warning: Be sure to install the `HotChocolate.Types.Sorting` NuGet package.
 
 ## AuthorizeAttribute
 

website/src/docs/hotchocolate/v10/security/index.md

@@ -18,9 +18,7 @@ Authorization on the other hand is something Hot Chocolate can provide some valu
 
 But let's start at the beginning with this. In order to add authorization capabilities to our schema add the following package to our project:
 
-```bash
-dotnet add package HotChocolate.AspNetCore.Authorization
-```
+<PackageInstallation packageName="HotChocolate.AspNetCore.Authorization" />
 
 In order to use the `@authorize`-directive we have to register it like the following with our schema:
 

website/src/docs/hotchocolate/v10/stitching.md

@@ -146,15 +146,11 @@ With this we have now a functioning GraphQL server with a simple hello world exa
 
 In order to make this server a stitching server we now have to add the Hot Chocolate stitching engine.
 
-```bash
-dotnet add package HotChocolate.Stitching
-```
+<PackageInstallation packageName="HotChocolate.Stitching" />
 
 and Subscription package if using AspNetCore
 
-```bash
-dotnet add package HotChocolate.AspNetCore.Subscriptions
-```
+<PackageInstallation packageName="HotChocolate.AspNetCore.Subscriptions" />
 
 Now that our GraphQL server is ready we can start to configure the endpoints of our remote schemas.
 

website/src/docs/hotchocolate/v11/api-reference/custom-attributes.md

@@ -52,7 +52,7 @@ public class Query
 }
 ```
 
-> ⚠️ **Note**: Be sure to install the `HotChocolate.Types.Filters` NuGet package.
+> Warning: Be sure to install the `HotChocolate.Types.Filters` NuGet package.
 
 ## UseSortingAttribute
 
@@ -69,7 +69,7 @@ public class Query
 }
 ```
 
-> ⚠️ **Note**: Be sure to install the `HotChocolate.Types.Sorting` NuGet package.
+> Warning: Be sure to install the `HotChocolate.Types.Sorting` NuGet package.
 
 ## AuthorizeAttribute