diff --git a/docusaurus.config.js b/docusaurus.config.js
index 91f819db..96e70e0e 100644
--- a/docusaurus.config.js
+++ b/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,
+ },
+ }
: {}),
}),
};
diff --git a/examples/examples.json b/examples/examples.json
new file mode 100644
index 00000000..ed631870
--- /dev/null
+++ b/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"]
+ }
+]
diff --git a/examples/examples.next b/examples/examples.next
new file mode 100644
index 00000000..b40b4d0a
--- /dev/null
+++ b/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"]
+ }
+]
diff --git a/package-lock.json b/package-lock.json
index 1ab7ec98..21103e06 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11,6 +11,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",
@@ -2769,6 +2772,11 @@
"node": ">=18.0"
}
},
+ "node_modules/@docusaurus/tsconfig": {
+ "version": "3.1.1",
+ "resolved": "https://registry.npmjs.org/@docusaurus/tsconfig/-/tsconfig-3.1.1.tgz",
+ "integrity": "sha512-FTBuY3KvaHfMVBgvlPmDQ+KS9Q/bYtVftq2ugou3PgBDJoQmw2aUZ4Sg15HKqLGbfIkxoy9t6cqE4Yw1Ta8Q1A=="
+ },
"node_modules/@docusaurus/types": {
"version": "3.1.1",
"resolved": "https://registry.npmjs.org/@docusaurus/types/-/types-3.1.1.tgz",
@@ -2915,6 +2923,52 @@
"node": ">=14"
}
},
+ "node_modules/@fortawesome/fontawesome-common-types": {
+ "version": "6.5.2",
+ "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-common-types/-/fontawesome-common-types-6.5.2.tgz",
+ "integrity": "sha512-gBxPg3aVO6J0kpfHNILc+NMhXnqHumFxOmjYCFfOiLZfwhnnfhtsdA2hfJlDnj+8PjAs6kKQPenOTKj3Rf7zHw==",
+ "hasInstallScript": true,
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/@fortawesome/fontawesome-svg-core": {
+ "version": "6.5.2",
+ "resolved": "https://registry.npmjs.org/@fortawesome/fontawesome-svg-core/-/fontawesome-svg-core-6.5.2.tgz",
+ "integrity": "sha512-5CdaCBGl8Rh9ohNdxeeTMxIj8oc3KNBgIeLMvJosBMdslK/UnEB8rzyDRrbKdL1kDweqBPo4GT9wvnakHWucZw==",
+ "hasInstallScript": true,
+ "peer": true,
+ "dependencies": {
+ "@fortawesome/fontawesome-common-types": "6.5.2"
+ },
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/@fortawesome/free-solid-svg-icons": {
+ "version": "6.5.2",
+ "resolved": "https://registry.npmjs.org/@fortawesome/free-solid-svg-icons/-/free-solid-svg-icons-6.5.2.tgz",
+ "integrity": "sha512-QWFZYXFE7O1Gr1dTIp+D6UcFUF0qElOnZptpi7PBUMylJh+vFmIedVe1Ir6RM1t2tEQLLSV1k7bR4o92M+uqlw==",
+ "hasInstallScript": true,
+ "dependencies": {
+ "@fortawesome/fontawesome-common-types": "6.5.2"
+ },
+ "engines": {
+ "node": ">=6"
+ }
+ },
+ "node_modules/@fortawesome/react-fontawesome": {
+ "version": "0.2.0",
+ "resolved": "https://registry.npmjs.org/@fortawesome/react-fontawesome/-/react-fontawesome-0.2.0.tgz",
+ "integrity": "sha512-uHg75Rb/XORTtVt7OS9WoK8uM276Ufi7gCzshVWkUJbHhh3svsUUeqXerrM96Wm7fRiDzfKRwSoahhMIkGAYHw==",
+ "dependencies": {
+ "prop-types": "^15.8.1"
+ },
+ "peerDependencies": {
+ "@fortawesome/fontawesome-svg-core": "~1 || ~6",
+ "react": ">=16.3"
+ }
+ },
"node_modules/@hapi/hoek": {
"version": "9.3.0",
"resolved": "https://registry.npmjs.org/@hapi/hoek/-/hoek-9.3.0.tgz",
@@ -18993,4 +19047,4 @@
}
}
}
-}
+}
\ No newline at end of file
diff --git a/package.json b/package.json
index 71f88a25..6103b623 100644
--- a/package.json
+++ b/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"
]
}
-}
+}
\ No newline at end of file
diff --git a/src/components/ExamplesPage.tsx b/src/components/ExamplesPage.tsx
new file mode 100644
index 00000000..ecc42539
--- /dev/null
+++ b/src/components/ExamplesPage.tsx
@@ -0,0 +1,314 @@
+import BrowserOnly from '@docusaurus/BrowserOnly';
+import React, { useEffect, useState } from "react";
+import Layout from "@theme/Layout";
+
+import clsx from "clsx";
+
+import {
+ faArrowRight,
+ faChevronDown,
+ faChevronUp,
+ faLink,
+ faTableList,
+ faTerminal,
+} from "@fortawesome/free-solid-svg-icons";
+import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
+
+export default function (props) {
+ return (
+