From 9610fdd90c5dbcc873ad63189c00f4d4ed74c394 Mon Sep 17 00:00:00 2001 From: Juri Date: Mon, 31 Jul 2023 16:11:46 +0200 Subject: [PATCH] feat(nx-dev): update terminal markdown embeds --- docs/README.md | 18 ++++++ docs/shared/getting-started/installation.md | 30 +++++++--- docs/shared/getting-started/intro.md | 16 ++++-- nx-dev/ui-markdoc/src/index.ts | 10 ++-- .../src/lib/nodes/fence.component.tsx | 49 +++++++++++------ .../{fence.schema.ts => fence.schema.tsx} | 1 + .../fences/terminal-output.component.tsx | 53 +++++------------- .../nodes/fences/terminal-shell.component.tsx | 29 ++++++++++ .../src/lib/tags/svg-animation.component.tsx | 55 +++++++++++++++++++ .../lib/tags/terminal-command.component.tsx | 33 ----------- .../src/lib/tags/terminal-video.component.tsx | 33 +++++++++++ .../src/lib/tags/video-loop.component.tsx | 32 ++++++----- 12 files changed, 239 insertions(+), 120 deletions(-) rename nx-dev/ui-markdoc/src/lib/nodes/{fence.schema.ts => fence.schema.tsx} (93%) create mode 100644 nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-shell.component.tsx create mode 100644 nx-dev/ui-markdoc/src/lib/tags/svg-animation.component.tsx delete mode 100644 nx-dev/ui-markdoc/src/lib/tags/terminal-command.component.tsx create mode 100644 nx-dev/ui-markdoc/src/lib/tags/terminal-video.component.tsx diff --git a/docs/README.md b/docs/README.md index bf590b581a..2597cf13f0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -67,6 +67,16 @@ You can add specific languages and a filename on the code snippet displayed. ‎``` ```` +#### Terminal command + +To display a terminal command, use: + +```` +‎```shell +‎ npx nx build +‎``` +```` + #### Terminal Output You can display your terminal output with a dedicated component the same way you would show code. @@ -85,6 +95,14 @@ You can optionally also pass a `path` like ‎``` ```` +#### Terminal Video Output + +You can have a more dynamic visualization of a terminal output by using the following component: + +``` +{% terminal-video src="/documentation/shared/images/caching/cache-terminal-animation.mp4" /%} +``` + #### Custom iframes We can display a special iframe and setting its width inside the document. diff --git a/docs/shared/getting-started/installation.md b/docs/shared/getting-started/installation.md index 7d37b35b08..314f95388a 100644 --- a/docs/shared/getting-started/installation.md +++ b/docs/shared/getting-started/installation.md @@ -5,24 +5,30 @@ Create a new Nx workspace using the following command: {% tabs %} {% tab label="npm" %} -{% terminal-command command="npx create-nx-workspace" /%} +```shell +npx create-nx-workspace +``` {% /tab %} {% tab label="yarn" %} -{% terminal-command command="npx create-nx-workspace --pm yarn" /%} +```shell +npx create-nx-workspace --pm yarn +``` {% /tab %} {% tab label="pnpm" %} -{% terminal-command command="npx create-nx-workspace --pm pnpm" /%} +```shell +npx create-nx-workspace --pm pnpm +``` {% /tab %} {% /tabs %} This will guide you through the setup, asking whether you want a monorepo or a standalone app and whether you want to start with a blank or a preconfigured setup. -```{% command="npx create-nx-workspace" %} +```{% command="npx create-nx-workspace" path="~" %} > NX Let's create a new workspace [https://nx.dev/getting-started/intro] @@ -48,7 +54,9 @@ Learn more about [running tasks](/core-features/run-tasks). If you want to add Nx to an existing repository run: -{% terminal-command command="npx nx@latest init" /%} +```shell +npx nx@latest init +``` You can also manually install the nx NPM package and create a [nx.json](https://nx.dev/reference/nx-json) to configure it. Learn more about [adopting Nx in an existing project](/recipes/adopting-nx) @@ -59,17 +67,23 @@ You can install Nx globally. Depending on your package manager, use one of the f {% tabs %} {% tab label="npm" %} -{% terminal-command command="npm install --global nx@latest" /%} +```shell +npm install --global nx@latest +``` {% /tab %} {% tab label="yarn" %} -{% terminal-command command="yarn global add nx@latest" /%} +```shell +yarn global add nx@latest +``` {% /tab %} {% tab label="pnpm" %} -{% terminal-command command="pnpm install --global nx@latest" /%} +```shell +pnpm install --global nx@latest +``` {% /tab %} {% /tabs %} diff --git a/docs/shared/getting-started/intro.md b/docs/shared/getting-started/intro.md index aeb5abe91b..8a6ee92076 100644 --- a/docs/shared/getting-started/intro.md +++ b/docs/shared/getting-started/intro.md @@ -7,17 +7,23 @@ If instead you want to jump right into it, run the following command. It will gu {% tabs %} {% tab label="npm" %} -{% terminal-command command="npx create-nx-workspace" /%} +```shell +npx create-nx-workspace +``` {% /tab %} {% tab label="yarn" %} -{% terminal-command command="npx create-nx-workspace --pm yarn" /%} +```shell +npx create-nx-workspace --pm yarn +``` {% /tab %} {% tab label="pnpm" %} -{% terminal-command command="npx create-nx-workspace --pm pnpm" /%} +```shell +npx create-nx-workspace --pm pnpm +``` {% /tab %} {% /tabs %} @@ -92,7 +98,9 @@ A modern Node server with scaffolding for Express, Fastify or Koa. There's also If you have an existing project and want to adopt Nx or migrate to Nx just run the following command which guides you through the migration process: -{% terminal-command command="npx nx@latest init" /%} +```shell +npx nx@latest init +``` Alternatively, here are some recipes that give you more details based on the technology stack you're using: diff --git a/nx-dev/ui-markdoc/src/index.ts b/nx-dev/ui-markdoc/src/index.ts index d8fc4637f0..8a08b9effa 100644 --- a/nx-dev/ui-markdoc/src/index.ts +++ b/nx-dev/ui-markdoc/src/index.ts @@ -39,9 +39,9 @@ import { Tab, Tabs } from './lib/tags/tabs.component'; import { tab, tabs } from './lib/tags/tabs.schema'; import { YouTube, youtube } from './lib/tags/youtube.component'; import { - TerminalCommand, - terminalCommand, -} from './lib/tags/terminal-command.component'; + TerminalVideo, + terminalVideo, +} from './lib/tags/terminal-video.component'; import { VideoLink, videoLink } from './lib/tags/video-link.component'; // TODO fix this export @@ -74,7 +74,7 @@ export const getMarkdocCustomConfig = ( tabs, 'title-card': titleCard, youtube, - 'terminal-command': terminalCommand, + 'terminal-video': terminalVideo, 'video-link': videoLink, }, }, @@ -98,7 +98,7 @@ export const getMarkdocCustomConfig = ( Tabs, TitleCard, YouTube, - TerminalCommand, + TerminalVideo, VideoLink, }, }); diff --git a/nx-dev/ui-markdoc/src/lib/nodes/fence.component.tsx b/nx-dev/ui-markdoc/src/lib/nodes/fence.component.tsx index 9332a5a555..c2c65e560a 100644 --- a/nx-dev/ui-markdoc/src/lib/nodes/fence.component.tsx +++ b/nx-dev/ui-markdoc/src/lib/nodes/fence.component.tsx @@ -27,9 +27,18 @@ function CodeWrapper(options: { command: string; path: string; isMessageBelow: boolean; + language: string; + children: string; // intentionally typed as such }): ({ children }: { children: ReactNode }) => JSX.Element { return ({ children }: { children: ReactNode }) => - options.command ? ( + options.language === 'shell' ? ( + + ) : options.command ? ( { @@ -76,23 +87,25 @@ export function Fence({
- { - setCopied(true); - }} - > - - + + + )} {showRescopeMessage && ( diff --git a/nx-dev/ui-markdoc/src/lib/nodes/fence.schema.ts b/nx-dev/ui-markdoc/src/lib/nodes/fence.schema.tsx similarity index 93% rename from nx-dev/ui-markdoc/src/lib/nodes/fence.schema.ts rename to nx-dev/ui-markdoc/src/lib/nodes/fence.schema.tsx index 6e645ef223..28764d3da0 100644 --- a/nx-dev/ui-markdoc/src/lib/nodes/fence.schema.ts +++ b/nx-dev/ui-markdoc/src/lib/nodes/fence.schema.tsx @@ -9,6 +9,7 @@ export const fence: Schema = { command: { type: 'String', default: '' }, path: { type: 'String', default: '~/workspace' }, process: { type: 'Boolean', render: false, default: true }, + enableCopy: { type: 'Boolean', default: true }, }, transform(node, config) { const attributes = node.transformAttributes(config); diff --git a/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-output.component.tsx b/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-output.component.tsx index 55fadc7a4f..c1ebf73462 100644 --- a/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-output.component.tsx +++ b/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-output.component.tsx @@ -1,6 +1,5 @@ -import { cx } from '@nx/nx-dev/ui-primitives'; import { ReactNode } from 'react'; -import { VideoLoop } from '../../tags/video-loop.component'; +import { TerminalShellWrapper } from './terminal-shell.component'; export function TerminalOutput({ content, @@ -13,44 +12,22 @@ export function TerminalOutput({ isMessageBelow: boolean; path: string; }): JSX.Element { - const isVideo = command.indexOf('.mp4') > -1; - return ( -
-
-
- - - + +
+
+

+ {path && ( + + {path} + + )} + ❯ +

+

{command}

- +
{content}
- {!isVideo && ( -
-
-

- {path && ( - - {path} - - )} - ❯ -

-

{command}

-
-
{content}
-
- )} - {isVideo && ( -
- -
- )} -
+ ); } diff --git a/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-shell.component.tsx b/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-shell.component.tsx new file mode 100644 index 0000000000..297042b2e7 --- /dev/null +++ b/nx-dev/ui-markdoc/src/lib/nodes/fences/terminal-shell.component.tsx @@ -0,0 +1,29 @@ +import { cx } from '@nx/nx-dev/ui-primitives'; +import { ReactNode } from 'react'; + +export function TerminalShellWrapper({ + isMessageBelow, + children, +}: { + isMessageBelow: boolean; + children: ReactNode; +}): JSX.Element { + return ( +
+
+
+ + + +
+ +
+ {children} +
+ ); +} diff --git a/nx-dev/ui-markdoc/src/lib/tags/svg-animation.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/svg-animation.component.tsx new file mode 100644 index 0000000000..3a4f83763f --- /dev/null +++ b/nx-dev/ui-markdoc/src/lib/tags/svg-animation.component.tsx @@ -0,0 +1,55 @@ +import { Schema } from '@markdoc/markdoc'; +import { useEffect, useRef } from 'react'; + +export const svgAnimation: Schema = { + render: 'SvgAnimation', + attributes: { + src: { + type: 'String', + required: true, + }, + + title: { + type: 'String', + required: true, + }, + }, +}; + +export function SvgAnimation({ + src, + title, +}: { + src: string; + title: string; +}): JSX.Element { + const objectRef = useRef(null); + + useEffect(() => { + if (objectRef.current) { + fetch(src) + .then((response) => response.text()) + .then((svgContent) => { + objectRef.current!.data = `data:image/svg+xml,${encodeURIComponent( + svgContent + )}`; + }) + .catch((error) => { + console.error('Error fetching SVG:', error); + }); + } + }, [src]); + + return ( +
+ + {title} + +
+ ); +} diff --git a/nx-dev/ui-markdoc/src/lib/tags/terminal-command.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/terminal-command.component.tsx deleted file mode 100644 index 9e3a2f852f..0000000000 --- a/nx-dev/ui-markdoc/src/lib/tags/terminal-command.component.tsx +++ /dev/null @@ -1,33 +0,0 @@ -import { Schema } from '@markdoc/markdoc'; -import { TerminalOutput } from '../nodes/fences/terminal-output.component'; - -export const terminalCommand: Schema = { - render: 'TerminalCommand', - attributes: { - command: { - type: 'String', - required: true, - }, - path: { - type: 'String', - required: false, - }, - }, -}; - -export function TerminalCommand({ - command, - path, -}: { - command: string; - path: string; -}): JSX.Element { - return ( - - ); -} diff --git a/nx-dev/ui-markdoc/src/lib/tags/terminal-video.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/terminal-video.component.tsx new file mode 100644 index 0000000000..2897d28382 --- /dev/null +++ b/nx-dev/ui-markdoc/src/lib/tags/terminal-video.component.tsx @@ -0,0 +1,33 @@ +import { VideoLoop } from './video-loop.component'; +import { Schema } from '@markdoc/markdoc'; +import { TerminalShellWrapper } from '../nodes/fences/terminal-shell.component'; + +export const terminalVideo: Schema = { + render: 'TerminalVideo', + attributes: { + src: { + type: 'String', + required: true, + }, + alt: { + type: 'String', + required: true, + }, + }, +}; + +export function TerminalVideo({ + src, + alt, +}: { + src: string; + alt: string; +}): JSX.Element { + return ( + +
+ +
+ + ); +} diff --git a/nx-dev/ui-markdoc/src/lib/tags/video-loop.component.tsx b/nx-dev/ui-markdoc/src/lib/tags/video-loop.component.tsx index fe037a7a8e..32df105a60 100644 --- a/nx-dev/ui-markdoc/src/lib/tags/video-loop.component.tsx +++ b/nx-dev/ui-markdoc/src/lib/tags/video-loop.component.tsx @@ -1,22 +1,17 @@ -import { Schema } from '@markdoc/markdoc'; -import { useEffect, useRef } from 'react'; +import { useEffect, useRef, useState } from 'react'; -export const videoLoop: Schema = { - render: 'VideoLoop', - attributes: { - src: { - type: 'String', - required: true, - }, - }, -}; - -export function VideoLoop({ src }: { src: string }): JSX.Element { - const videoRef = useRef(null); +export function VideoLoop({ + src, + alt, +}: { + src: string; + alt: string; +}): JSX.Element { + const videoRef = useRef(null); useEffect(() => { let observer: IntersectionObserver; - let videoElement = videoRef.current as HTMLVideoElement | null; + let videoElement = videoRef.current; if (videoElement) { observer = new IntersectionObserver( @@ -48,6 +43,13 @@ export function VideoLoop({ src }: { src: string }): JSX.Element { return ( ); }