Begin docs website (#875)

- **bump: version 0.1.11**
- **clarify `courseware` package responsibilities**
- **wip - vitepress docs**
- **checkpoint: working import from MR...**
- **add target imports**
- **test: use a local import. works.**
- **add todo imports**
- **import ViewData from common... works!**
- **add common-ui composable imports... working**
- **add FallingLettersQuesion import... working**
- **add vue imports... working**
- **add vitepress vendored docs...**
- **rm testComponent**
- **"working" render of fallingLetters component.**
- **rm FallingLettersWrapper**
- **simplify usage of FallingLetters**
- **add logo + brand color css**
- **branding for gradient defs**
- **tmp: add existing vitepress template comonents...**
- **add custom HERO template...**
- **add docs deploy workflow**

Author: NiloCK

.github/workflows/docs-deploy.yml

@@ -0,0 +1,66 @@
+# Sample workflow for building and deploying a VitePress site to GitHub Pages
+#
+name: Deploy VitePress site to Pages
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [master]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      # - uses: pnpm/action-setup@v3 # Uncomment this block if you're using pnpm
+      #   with:
+      #     version: 9 # Not needed if you've set "packageManager" in package.json
+      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm # or pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Install dependencies
+        run: npm ci # or pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/.vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -47,3 +47,8 @@ ignore
 
 # node pouchdb userdbs that get popped by `db` package sometimes. nuisance.
 userdb-Guest
+
+# vitepress docs build/dev output
+
+docs/.vitepress/dist
+docs/.vitepress/cache

agent/docs-vendoring/vitepress/config.ts

@@ -0,0 +1,139 @@
+import { createRequire } from 'module'
+import { defineAdditionalConfig, type DefaultTheme } from 'vitepress'
+
+const require = createRequire(import.meta.url)
+const pkg = require('vitepress/package.json')
+
+export default defineAdditionalConfig({
+  lang: 'en-US',
+  description: 'Vite & Vue powered static site generator.',
+
+  themeConfig: {
+    nav: nav(),
+
+    sidebar: {
+      '/guide/': { base: '/guide/', items: sidebarGuide() },
+      '/reference/': { base: '/reference/', items: sidebarReference() }
+    },
+
+    editLink: {
+      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
+      text: 'Edit this page on GitHub'
+    },
+
+    footer: {
+      message: 'Released under the MIT License.',
+      copyright: 'Copyright © 2019-present Evan You'
+    }
+  }
+})
+
+function nav(): DefaultTheme.NavItem[] {
+  return [
+    {
+      text: 'Guide',
+      link: '/guide/what-is-vitepress',
+      activeMatch: '/guide/'
+    },
+    {
+      text: 'Reference',
+      link: '/reference/site-config',
+      activeMatch: '/reference/'
+    },
+    {
+      text: pkg.version,
+      items: [
+        {
+          text: 'Changelog',
+          link: 'https://github.com/vuejs/vitepress/blob/main/CHANGELOG.md'
+        },
+        {
+          text: 'Contributing',
+          link: 'https://github.com/vuejs/vitepress/blob/main/.github/contributing.md'
+        }
+      ]
+    }
+  ]
+}
+
+function sidebarGuide(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Introduction',
+      collapsed: false,
+      items: [
+        { text: 'What is VitePress?', link: 'what-is-vitepress' },
+        { text: 'Getting Started', link: 'getting-started' },
+        { text: 'Routing', link: 'routing' },
+        { text: 'Deploy', link: 'deploy' }
+      ]
+    },
+    {
+      text: 'Writing',
+      collapsed: false,
+      items: [
+        { text: 'Markdown Extensions', link: 'markdown' },
+        { text: 'Asset Handling', link: 'asset-handling' },
+        { text: 'Frontmatter', link: 'frontmatter' },
+        { text: 'Using Vue in Markdown', link: 'using-vue' },
+        { text: 'Internationalization', link: 'i18n' }
+      ]
+    },
+    {
+      text: 'Customization',
+      collapsed: false,
+      items: [
+        { text: 'Using a Custom Theme', link: 'custom-theme' },
+        {
+          text: 'Extending the Default Theme',
+          link: 'extending-default-theme'
+        },
+        { text: 'Build-Time Data Loading', link: 'data-loading' },
+        { text: 'SSR Compatibility', link: 'ssr-compat' },
+        { text: 'Connecting to a CMS', link: 'cms' }
+      ]
+    },
+    {
+      text: 'Experimental',
+      collapsed: false,
+      items: [
+        { text: 'MPA Mode', link: 'mpa-mode' },
+        { text: 'Sitemap Generation', link: 'sitemap-generation' }
+      ]
+    },
+    { text: 'Config & API Reference', base: '/reference/', link: 'site-config' }
+  ]
+}
+
+function sidebarReference(): DefaultTheme.SidebarItem[] {
+  return [
+    {
+      text: 'Reference',
+      items: [
+        { text: 'Site Config', link: 'site-config' },
+        { text: 'Frontmatter Config', link: 'frontmatter-config' },
+        { text: 'Runtime API', link: 'runtime-api' },
+        { text: 'CLI', link: 'cli' },
+        {
+          text: 'Default Theme',
+          base: '/reference/default-theme-',
+          items: [
+            { text: 'Overview', link: 'config' },
+            { text: 'Nav', link: 'nav' },
+            { text: 'Sidebar', link: 'sidebar' },
+            { text: 'Home Page', link: 'home-page' },
+            { text: 'Footer', link: 'footer' },
+            { text: 'Layout', link: 'layout' },
+            { text: 'Badge', link: 'badge' },
+            { text: 'Team Page', link: 'team-page' },
+            { text: 'Prev / Next Links', link: 'prev-next-links' },
+            { text: 'Edit Link', link: 'edit-link' },
+            { text: 'Last Updated Timestamp', link: 'last-updated' },
+            { text: 'Search', link: 'search' },
+            { text: 'Carbon Ads', link: 'carbon-ads' }
+          ]
+        }
+      ]
+    }
+  ]
+}

agent/docs-vendoring/vitepress/guide/asset-handling.md

@@ -0,0 +1,63 @@
+# Asset Handling
+
+## Referencing Static Assets
+
+All Markdown files are compiled into Vue components and processed by [Vite](https://vitejs.dev/guide/assets.html). You can, **and should**, reference any assets using relative URLs:
+
+```md
+![An image](./image.png)
+```
+
+You can reference static assets in your markdown files, your `*.vue` components in the theme, styles and plain `.css` files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used Vite, Vue CLI, or webpack's `file-loader`.
+
+Common image, media, and font filetypes are detected and included as assets automatically.
+
+::: tip Linked files are not treated as assets
+PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the [`public`](#the-public-directory) directory of your project.
+:::
+
+All referenced assets, including those using absolute paths, will be copied to the output directory with a hashed file name in the production build. Never-referenced assets will not be copied. Image assets smaller than 4kb will be base64 inlined - this can be configured via the [`vite`](../reference/site-config#vite) config option.
+
+All **static** path references, including absolute paths, should be based on your working directory structure.
+
+## The Public Directory
+
+Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include `robots.txt`, favicons, and PWA icons.
+
+You can place these files in the `public` directory under the [source directory](./routing#source-directory). For example, if your project root is `./docs` and using default source directory location, then your public directory will be `./docs/public`.
+
+Assets placed in `public` will be copied to the root of the output directory as-is.
+
+Note that you should reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
+
+## Base URL
+
+If your site is deployed to a non-root URL, you will need to set the `base` option in `.vitepress/config.js`. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `'/bar/'` (it should always start and end with a slash).
+
+All your static asset paths are automatically processed to adjust for different `base` config values. For example, if you have an absolute reference to an asset under `public` in your markdown:
+
+```md
+![An image](/image-inside-public.png)
+```
+
+You do **not** need to update it when you change the `base` config value in this case.
+
+However, if you are authoring a theme component that links to assets dynamically, e.g. an image whose `src` is based on a theme config value:
+
+```vue
+<img :src="theme.logoPath" />
+```
+
+In this case it is recommended to wrap the path with the [`withBase` helper](../reference/runtime-api#withbase) provided by VitePress:
+
+```vue
+<script setup>
+import { withBase, useData } from 'vitepress'
+
+const { theme } = useData()
+</script>
+
+<template>
+  <img :src="withBase(theme.logoPath)" />
+</template>
+```

agent/docs-vendoring/vitepress/guide/cms.md

@@ -0,0 +1,56 @@
+---
+outline: deep
+---
+
+# Connecting to a CMS
+
+## General Workflow
+
+Connecting VitePress to a CMS will largely revolve around [Dynamic Routes](./routing#dynamic-routes). Make sure to understand how it works before proceeding.
+
+Since each CMS will work differently, here we can only provide a generic workflow that you will need to adapt to your specific scenario.
+
+1. If your CMS requires authentication, create an `.env` file to store your API tokens and load it so:
+
+    ```js
+    // posts/[id].paths.js
+    import { loadEnv } from 'vitepress'
+
+    const env = loadEnv('', process.cwd())
+    ```
+
+2. Fetch the necessary data from the CMS and format it into proper paths data:
+
+    ```js
+    export default {
+      async paths() {
+        // use respective CMS client library if needed
+        const data = await (await fetch('https://my-cms-api', {
+          headers: {
+            // token if necessary
+          }
+        })).json()
+
+        return data.map(entry => {
+          return {
+            params: { id: entry.id, /* title, authors, date etc. */ },
+            content: entry.content
+          }
+        })
+      }
+    }
+    ```
+
+3. Render the content in the page:
+
+    ```md
+    # {{ $params.title }}
+
+    - by {{ $params.author }} on {{ $params.date }}
+
+    <!-- @content -->
+    ```
+
+## Integration Guides
+
+If you have written a guide on integrating VitePress with a specific CMS, please use the "Edit this page" link below to submit it here!