Migrating examples from runme.dev to docs.runme.dev

docusaurus.config.js

@@ -3,6 +3,7 @@
 
 const lightCodeTheme = require("prism-react-renderer").themes.github;
 const darkCodeTheme = require("prism-react-renderer").themes.dracula;
+const fs = require('fs').promises;
 
 const siteName = "Runme.dev";
 const twitterHandle = "@statefulhq";
@@ -55,6 +56,46 @@ const config = {
         },
       };
     },
+    async function examplesInDocs(context, options) {
+      return {
+        name: 'examples-in-docs',
+        async contentLoaded({ content, actions }) {
+          const { createData, addRoute } = actions;
+          const examples = await fs.readFile('./examples/examples.json', 'utf8');
+          const examplesJsonPath = await createData(
+            'examples.json',
+            examples,
+          );
+
+          addRoute({
+            path: '/examples',
+            component: '@site/src/components/ExamplesPage',
+            modules: {
+              // propName -> JSON file path
+              examples: examplesJsonPath,
+            },
+            exact: true,
+          });
+
+          const examplesJson = JSON.parse(examples);
+          examplesJson.forEach(async (example) => {
+            const exampleJsonPath = await createData(
+              `example-${example.slug}.json`,
+              JSON.stringify(example),
+            );
+            addRoute({
+              path: `/examples/${example.slug}`,
+              component: '@site/src/components/ExamplesPage',
+              modules: {
+                // propName -> JSON file path
+                example: exampleJsonPath,
+              },
+              exact: true,
+            });
+          });
+        },
+      };;
+    },
     [
       "@docusaurus/plugin-pwa",
       {
@@ -182,15 +223,15 @@ const config = {
        * credentials available in 1password
        */
       ...(process.env.ALGOLIA_API_KEY &&
-      process.env.ALGOLIA_INDEX_NAME &&
-      process.env.ALGOLIA_APP_ID
+        process.env.ALGOLIA_INDEX_NAME &&
+        process.env.ALGOLIA_APP_ID
         ? {
-            algolia: {
-              apiKey: process.env.ALGOLIA_API_KEY,
-              indexName: process.env.ALGOLIA_INDEX_NAME,
-              appId: process.env.ALGOLIA_APP_ID,
-            },
-          }
+          algolia: {
+            apiKey: process.env.ALGOLIA_API_KEY,
+            indexName: process.env.ALGOLIA_INDEX_NAME,
+            appId: process.env.ALGOLIA_APP_ID,
+          },
+        }
         : {}),
     }),
 };

examples/examples.json

@@ -0,0 +1,115 @@
+[
+  {
+    "title": "Hello World!",
+    "description": "A simple example to create a new markdown file that installs and runs the dancing-bear with npm, run it in the notebook UX, and then use the `runme` CLI to parse and run the dancing bear in the terminal.",
+    "slug": "hello-world",
+    "tags": ["notebook", "cli", "hello world"],
+    "runme": "https://runme.dev/api/runme?repository=https%3A%2F%2Fgithub.com%2Fsourishkrout%2Floon.git&fileToOpen=AI.md",
+    "repo": "https://github.com/stateful/vscode-runme/blob/main/examples/README.md",
+    "docs": "https://docs.runme.dev/install",
+    "img": "/graphics/hello-world.gif"
+  },
+  {
+    "title": "Image rendering in notebook cells with OpenAI (image MIME type)",
+    "description": "Changing the mimeType in the notebook cell configuration (image/png) let's you specify how you want the output rendered, in this case the image binary generated by OpenAI.",
+    "webm": "https://media.graphassets.com/XfI7g2nYTgmwSGg75CDc",
+    "mp4": "https://media.graphassets.com/N4iyhZ7S8WmssHAAQnbA",
+    "slug": "rendering-an-image-openai",
+    "tags": ["notebook", "render", "openai", "mime", "jpg", "image", "output"],
+    "runme": "https://runme.dev/api/runme?repository=https%253A%252F%252Fgithub.com%252Fstateful%252Fvscode-runme.git%2526fileToOpen%253D%252Fexamples%252FREADME.md",
+    "repo": "https://github.com/sourishkrout/loon",
+    "docs": "https://docs.runme.dev/configuration#supported-mime-types"
+  },
+  {
+    "title": "Integration testing a markdown in Github Actions",
+    "description": "Avoid having to maintain multiple workflows for building, testing and deploying your application and instead, document them in markdown and have them used by your contributors and CI/CD. Find out in this example how we manage workflows in our `stateful/runmejs` project using Runme.",
+    "img": "/graphics/runme-in-ci.png",
+    "slug": "integration-testing-markdown-gh-action",
+    "runme": "https://runme.dev/api/runme?repository=https%3A%2F%2Fgithub.com%2Fstateful%2Frunmejs.git&fileToOpen=CONTRIBUTING.md",
+    "repo": "https://github.com/stateful/runmejs",
+    "docs": "https://docs.runme.dev/integrations#github-action",
+    "tags": ["cli", "testing", "markdown", "github", "action", "ci/cd", "terminal"]
+  },
+  {
+    "title": "Hardening Ubuntu server",
+    "description": "Enhances the server's overall security posture, encourages continuous improvement, and safeguards against future attacks,",
+    "mp4": "https://media.graphassets.com/RiKBWblNSbSR86ZcAVTa",
+    "webm": "https://media.graphassets.com/NPgIDIcrRaiDt6prS8VD",
+    "slug": "Hardening-Ubuntu-server",
+    "runme": "https://runme.dev/api/runme?repository=https%3A%2F%2Fgithub.com%2Fstateful%2Fhardening-ubuntu-server%2Fblob%2Fmain%2FREADME.md",
+    "repo": "https://github.com/stateful/hardening-ubuntu-server",
+    "docs": "https://docs.runme.dev/architecture",
+    "tags": ["cli", "markdown", "ci/cd", "terminal", "ubuntu", "security"]
+  },
+  {
+    "title": "Explore large JSON files interactively with antonmedv/fx",
+    "description": "Create interactive workflows that allow your contributor to inspect their environment using popular terminal tools right within VS Code.",
+    "img": "/graphics/fx-demo.gif",
+    "slug": "explore-json-fx",
+    "runme": "https://runme.dev/api/runme?repository=https%253A%252F%252Fgithub.com%252Fstateful%252Fvscode-runme.git%2526fileToOpen%253D%252Fexamples%252FREADME.md",
+    "tags": ["notebook", "fx", "json", "render"]
+  },
+  {
+    "title": "Launching a Runme notebook with a web link",
+    "description": "With Runme you can bootstrap the onboarding of your contributors interactively through a notebook. With the Runme link you can save developers time having to manually clone the repository and direct them to the right document that help them to get productive quickly.",
+    "img": "/graphics/runme-link-demo.gif",
+    "slug": "launch-notebook-web-link",
+    "runme": "https://runme.dev/api/runme?repository=https%3A%2F%2Fgithub.com%2Fstateful%2Frunmejs.git&fileToOpen=CONTRIBUTING.md",
+    "docs": "https://docs.runme.dev/features#run-with-runme-deep-linking",
+    "tags": ["notebook", "web", "education", "tutorial", "onboarding"]
+  },
+  {
+    "title": "Render notebook cell output as a table (csv MIME type)",
+    "description": "If you want to render a sortable table instead of comma delimited text with your cell output, it's as simple as going into the cell configuration and changing the mimetype to `text/csv` then re-running the cell. This is one of many super useful available MIME types you can take advantage of in your Runme notebook.",
+    "img": "/graphics/mime-type-demo.gif",
+    "slug": "custom-renderer-table-mime",
+    "docs": "https://docs.runme.dev/configuration#supported-mime-types",
+    "tags": ["notebook", "mime", "render", "output", "table"]
+  },
+  {
+    "title": "Chaining output between markdown commands",
+    "description": "With the `$__` parameter you can transfer the stdout result of a previous cell into your next execution.",
+    "img": "/graphics/chaining-demo.gif",
+    "slug": "chain-output-between-commands",
+    "docs": "https://docs.runme.dev/features#chain-cell-output",
+    "tags": ["notebook", "cli", "output", "chaining", "markdown", "workflow", "terminal"]
+  },
+  {
+    "title": "Vercel deployment workflow in a notebook",
+    "description": "Runme integrates with cloud services such as Vercel or Deno cloud to make deploying on the edge interactive and fun!",
+    "img": "/graphics/integrations.gif",
+    "slug": "vercel-deploy-in-notebook",
+    "docs": "https://docs.runme.dev/integrations#nextjs-app-on-vercel",
+    "tags": ["notebook", "vercel", "integration", "deploy"]
+  },
+  {
+    "title": "Running Docker commands from markdown with our CLI",
+    "description": "Runme can share the same terminal session across CLI and notebook allowing you to run flexible Docker workflows between VS Code and your terminal.",
+    "img": "/graphics/docker-demo.gif",
+    "slug": "running-docker-markdown-cli",
+    "tags": ["notebook", "markdown", "docker"]
+  },
+  {
+    "title": "Notebook LSP Support",
+    "description": "Runme notebooks come with support of multiple script and declaritive languages, e.g. YAML, providing you text highlighting and auto-completion feature.",
+    "img": "/graphics/lsp-demo.gif",
+    "slug": "lsp-support",
+    "tags": ["notebook", "lsp", "language"]
+  },
+  {
+    "title": "Consistant Environment State",
+    "description": "Execute markdown cells in VS Code and keep environment variables persistent. This allows you to create a click to play notebook experience for running your markdown in the browser, or VS Code with Runme.",
+    "img": "/graphics/notebook-transparent.gif",
+    "slug": "environment-state",
+    "tags": ["environment", "workflow", "state"]
+  },
+  {
+    "title": "Runme in DevContainer",
+    "description": "The VS Code window attaches to an instance of the container image and transparently mounts the file system so changes are reflected locally.",
+    "mp4": "/videos/devcontainer.mp4",
+    "webm": "/videos/devcontainer.webm",
+    "runme": "https://runme.dev/api/runme?repository=https%253A%252F%252Fgithub.com%252Fstateful%252Fblog-examples.git%2526fileToOpen%253D%252Fdevcontainer%252Fsandbox.md",
+    "slug": "devcontainer",
+    "tags": ["devcontainer", "workspace", "ephemeral"]
+  }
+]

examples/examples.next

@@ -0,0 +1,23 @@
+[
+  {
+    "title": "Github Actions workflows UX (from a URL)",
+    "description": "This is a description of the thing this does and why it's cool",
+    "img": "https://media.graphassets.com/mbfC7eMfSHaKGeXvvWh2",
+    "slug": "gh-action-workflow-ux",
+    "tags": ["notebook", "github", "workflows", "ux", "action"]
+  },
+  {
+    "title": "Terminals embeded in your notebook cells",
+    "description": "This is a description of the thing this does and why it's cool",
+    "img": "https://media.graphassets.com/mbfC7eMfSHaKGeXvvWh2",
+    "slug": "terminals-embeded-notebook-cells",
+    "tags": ["notebook", "terminal"]
+  },
+  {
+    "title": "Click to send a SMS (Twilio) from a notebook",
+    "description": "This is a description of the thing this does and why it's cool",
+    "img": "https://media.graphassets.com/mbfC7eMfSHaKGeXvvWh2",
+    "slug": "sent-sms-twilio-notebook",
+    "tags": ["notebook", "sms", "twilio"]
+  }
+]

package.json

@@ -17,6 +17,9 @@
     "@docusaurus/core": "3.1.1",
     "@docusaurus/plugin-pwa": "^3.1.1",
     "@docusaurus/preset-classic": "3.1.1",
+    "@docusaurus/tsconfig": "3.1.1",
+    "@fortawesome/free-solid-svg-icons": "^6.5.2",
+    "@fortawesome/react-fontawesome": "^0.2.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.1.0",
     "prism-react-renderer": "^2.3.0",
@@ -47,4 +50,4 @@
       "last 1 safari version"
     ]
   }
-}
+}