revise: updates wdl-docs to the new site structure and content

This commit updates the documentation site with the following:

- a new theme that is more in line with the WDL brand,
- updates to nearly all the examples, which now conform to WDL v1.2,
- some updated content (e.g., the values and the reference section)
  and some content that I deemed too noisy for the main documentation
  (namely, cookbooks, which have been migrated
  [here](https://github.com/openwdl/cookbook/)), and
- a more straightforward learning path for new users to WDL.

Co-authored-by: Elizabeth Kiernan <[email protected]>

.github/workflows/docs.yml

@@ -0,0 +1,47 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "latest"
+      - run: npm install && npm run docs:build
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          name: "WDL Documentation"
+          path: ".vitepress/dist"
+  deploy:
+    needs: build
+    if: success() && github.ref == 'refs/heads/main'
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+        with:
+          artifact_name: "WDL Documentation"

.gitignore

@@ -1,2 +1,8 @@
-
 .DS_Store
+node_modules/
+
+# Disable the Vitepress cache.
+.vitepress/cache/*
+
+# Disable the Vitepress distribution folder.
+.vitepress/dist/*

.vitepress/config.mts

@@ -0,0 +1,134 @@
+import { defineConfig } from "vitepress";
+import axios from "axios";
+
+const url =
+  "https://raw.githubusercontent.com/stjude-rust-labs/sprocket-vscode/refs/heads/main/syntaxes/wdl.tmGrammar.json";
+
+/**
+ * Gets the current version of the Sprocket TextMate grammar.
+ * @returns the TextMate grammar as a JavaScript object
+ */
+async function getGrammar() {
+  try {
+    var response = await axios.get(url);
+    return response.data;
+  } catch (error) {
+    console.error(`error occurred: ${error}`);
+    throw error;
+  }
+}
+
+export default defineConfig({
+  title: "Workflow Description Language (WDL) Documentation",
+  description: "Guides for the Workflow Description Language (WDL).",
+  appearance: "force-dark",
+  base: "/wdl-docs/",
+  ignoreDeadLinks: ["./LICENSE"],
+  themeConfig: {
+    /**
+     * Logo and site title.
+     */
+    logo: {
+      src: "/logo-only.svg",
+      alt: "The Workflow Description Language (WDL) logo.",
+    },
+    siteTitle: "Documentation",
+
+    /**
+     * Navbar.
+     */
+    nav: [],
+
+    socialLinks: [
+      {
+        icon: "slack",
+        link: "https://join.slack.com/t/openwdl/shared_invite/zt-ctmj4mhf-cFBNxIiZYs6SY9HgM9UAVw",
+      },
+      { icon: "github", link: "https://github.com/openwdl/wdl-docs" },
+    ],
+
+    search: {
+      provider: "local",
+    },
+
+    /**
+     * Sidebar.
+     */
+    sidebar: [
+      { text: "Overview", link: "/overview" },
+      {
+        text: "Getting Started",
+        items: [
+          { text: "Quickstart", link: "/getting-started/quickstart" },
+          { text: "Ecosystem", link: "/getting-started/ecosystem" },
+          { text: "Getting help", link: "/getting-started/getting-help" },
+          { text: "Contributing", link: "/getting-started/contributing" },
+        ],
+      },
+      {
+        text: "Language Guide",
+        items: [
+          { text: "Variables", link: "/language-guide/variables.md" },
+          { text: "Structs", link: "/language-guide/structs.md" },
+          { text: "Tasks", link: "/language-guide/tasks.md" },
+          { text: "Workflows", link: "/language-guide/workflows.md" },
+          { text: "Imports", link: "/language-guide/imports.md" },
+        ],
+      },
+      {
+        text: "Design Patterns",
+        items: [
+          {
+            text: "Linear chaining",
+            link: "/design-patterns/linear-chaining/index.md",
+          },
+          { text: "Multiple I/O", link: "/design-patterns/multiple-io/index.md" },
+          { text: "Branch and merge", link: "/design-patterns/branch-and-merge/index.md" },
+          { text: "Task aliasing", link: "/design-patterns/task-aliasing/index.md" },
+          { text: "Conditional statement", link: "/design-patterns/conditional-statement/index.md" },
+          { text: "Scatter-gather", link: "/design-patterns/scatter-gather/index.md" },
+        ],
+      },
+      {
+        text: "Reference",
+        items: [
+          {
+            text: "Standard Library",
+            items: [
+              {
+                text: "Numeric functions",
+                link: "/reference/stdlib/numeric",
+              },
+              {
+                text: "String functions",
+                link: "/reference/stdlib/string",
+              },
+              {
+                text: "File functions",
+                link: "/reference/stdlib/file",
+              },
+            ],
+            collapsed: true,
+          },
+        ],
+      },
+      {
+        text: "Links",
+        items: [
+          {
+            text: "Cookbook",
+            link: "https://github.com/openwdl/cookbook"
+          }
+        ]
+      },
+    ],
+  },
+  markdown: {
+    theme: "github-dark",
+    shikiSetup: async function (highlighter) {
+      // Adds the WDL TextMate grammar from the `stjude-rust-labs/sprocket-vscode` repo
+      // to the Shiki highlighter.
+      await highlighter.loadLanguage(getGrammar());
+    },
+  },
+});

.vitepress/theme/index.ts

@@ -0,0 +1,17 @@
+// https://vitepress.dev/guide/custom-theme
+import { h } from "vue";
+import type { Theme } from "vitepress";
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+
+export default {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // https://vitepress.dev/guide/extending-default-theme#layout-slots
+    });
+  },
+  enhanceApp({ app, router, siteData }) {
+    // ...
+  },
+} satisfies Theme;