initial tool gatsby migration

docs/.github/workflows/pages-publish.yml

@@ -0,0 +1,87 @@
+name: Gatsby GHPages Publish
+# NOTE: This is designed to work for a site living in the /docs folder. You'll need to make changes if it is not.
+on:
+  push:
+    branches:
+      - docs
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ./docs/.nvmrc
+          cache-dependency-path: ./docs/package.json
+          cache: yarn
+
+      - name: Get correct version of Yarn
+        run: corepack enable; yarn set version berry
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v3
+        with:
+          # Automatically inject pathPrefix in your Gatsby configuration file.
+          #
+          # You may remove this line if you want to manage the configuration yourself.
+          static_site_generator: gatsby
+
+
+      - name: Restore cache
+        uses: actions/cache@v3
+        with:
+          path: |
+            ./docs/public
+            ./docs/.cache
+          key: ${{ runner.os }}-gatsby-build-${{ hashFiles('public') }}
+          restore-keys: |
+            ${{ runner.os }}-gatsby-build-
+
+      - name: Install dependencies
+        working-directory: ./docs
+        run: yarn install --immutable --immutable-cache
+
+      - name: Build with Gatsby
+        working-directory: ./docs
+        env:
+          PREFIX_PATHS: 'true'
+        run: yarn run build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ./docs/public
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

docs/.gitignore

@@ -1,11 +1,30 @@
-*.gem
-.bundle
-.sass-cache
-_site
-.jekyll-cache
-Gemfile.lock
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
 node_modules
 
-.jekyll-metadata
+# gatsby files
+.cache/
+public
+
+# Mac files
 .DS_Store
-resources/pocket\.md
+
+# Yarn
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+# Yarn
+yarn-error.log
+.pnp/
+.pnp.js
+# Yarn Integrity file
+.yarn-integrity

docs/.nvmrc

@@ -0,0 +1 @@
+v18

docs/.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "👷 Rebuild Gatsby Site",
+      "command": "yarn exec gatsby build",
+      "request": "launch",
+      "type": "node-terminal"
+    },
+    {
+      "name": "🗑️ Clean Gatsby Build",
+      "command": "yarn exec gatsby clean",
+      "request": "launch",
+      "type": "node-terminal"
+    },
+    {
+      "name": "📦 Upgrade Gatsby Theme",
+      "command": "yarn up @riverscapes/gatsby-theme",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

docs/.yarnrc.yml

@@ -0,0 +1 @@
+nodeLinker: node-modules

docs/Docs.code-workspace

@@ -0,0 +1,58 @@
+{
+  "folders": [
+    {
+      "name": "📜 Docs",
+      // Depending on where this workspace file ends up you may need to adjust this path "." is for when it is in the same folder as `gatsby-config.ts`
+      "path": "."
+    },
+    {
+      // The root folder is necessary so that this workspace can access git. The path will need to be adjuested depending on where this workspace file ends up.
+      // ".." is appropriate if this workspace file is in `ROOT/docs`
+      "name": "🏠 Root",
+      "path": ".."
+    },
+  ],
+  "settings": {
+    // TODO: Add your own site name here. Replace "GATSBYDOCS" with your site name or "QRiS Docs -" or whatever you want to see in the window title. 
+    "window.title": "GATSBYDOCS${separator}${activeEditorShort}${separator}${rootName}",
+    "[mdx]": {
+      "editor.wordWrap": "on"
+    },
+    "css.lint.validProperties": ["composes"],
+    "workbench.colorCustomizations": {
+			"titleBar.activeBackground": "#001768",
+      "sideBar.background": "#242132",
+			"editor.background": "#1e1c2c"
+		},
+    "editor.tabSize": 2,
+    "editor.codeActionsOnSave": {
+      "source.fixAll.eslint": "explicit"
+    },
+    "files.watcherExclude": {
+      "**/node_modules/**": true,
+      "**/.cache/**": true
+    },
+    "search.exclude": {
+      "**/node_modules/**": true,
+      "**/.cache/**": true,
+      "**/public/**": true,
+      "**/dist/**": true,
+    },
+    "files.exclude": {
+      "**/node_modules/**": true
+    }
+  },
+  "extensions": {
+    "recommendations": [
+      "GitHub.copilot",
+      "GitHub.copilot-chat",
+      "eriklynd.json-tools",
+      "yzhang.markdown-all-in-one",
+      "unifiedjs.vscode-mdx",
+      "dbaeumer.vscode-eslint",
+      "christian-kohler.npm-intellisense",
+      "mhutchie.git-graph"
+    ]
+  },
+  "terminal.integrated.defaultProfile.linux": "zsh"
+}

docs/README.md

@@ -0,0 +1,103 @@
+# Clean template site
+
+## Getting started for writing content
+
+1. Open up the `Docs.code-workspace` file in VSCode. This should open up the workspace and put you in the right place to run the site.
+2. Make sure you are running node > v18 and have access to yarn at the command line
+
+```bash
+> node --version
+v18.16.0
+
+> yarn --version
+3.6.1
+```
+
+3. If yarn insn't found you may need to install it: `npm install --global yarn`
+
+***The version of yarn isn't that important for content writers. We just run this command to make sure it's installed.***
+
+4. Open up a terminal window in VSCode and run `yarn install` to install all the dependencies.
+5. Run `yarn start` to start the dev server and develop locally.
+6. If you think something is broken or weird you can run `yarn clean` to clear the cache and then `yarn start` again to see if that fixes it. We also have `yarn start:clean` that combines these two steps.
+
+
+## Creating a new `./docs` site
+
+1. Copy everything (excluding `node_modules`, `.cache` and `public`) in this `./template` folder to a `./docs` subfolder in your desired repo. **NOTE: Make SURE to get all the dot-prefixed hidden files and folders includeing `.vscode`.**
+2. Open the `Docs.code-workspace` in the new location. 
+   - *You may need to open the workspace file and adjust the paths inside it if you move it to a different location.*
+   - For those of us with nvm installed (typically non-windows users) This should put your terminal in the right place so that the `.nvmrc` file registers and the correct version of node is installed. 
+3. open `gatsby-config.ts` and change all the **TODO** items:
+  - `pathPrefix`: If this site is going to live at a subpath like `https://example.com/useless-site`, then change this to `/useless-site` **NOTE: Case matters**
+  - `start_url`: Should match the `pathPrefix` if you have one
+4. Open a terminal and make sure you are in the `./docs` folder with the correct version of Nodejs
+5. Run `yarn install` inside the `./docs` folder to install all the dependencies
+6. RUn `yarn start` inside the `./docs` folder to start the dev server and develop locally.
+7. Now move the 2 yml files in the root of your `.git` repo. They are living in the `.github/workflows` folder next to this README.md file but they will need to be moved to the root of whatever repo they end up in.
+   1. `/.github/workflows/pages-publish.yml`
+   2. `/.github/workflows/pages-validate.yml`
+8. Move the entire `.devcontainer` folder to the root of your repo. This is the folder that contains the `Dockerfile` and `devcontainer.json` files.
+9. Once you push these files push the whole mess to Github and then go to the repo settings and enable Github Pages:
+   1. Repo Settings
+   2. Pages
+   3. Build and deployment --> Source --> Select `Github Actions`
+   4. Wait for it to build and deploy.
+
+## Upgrading a site to the latest version of Gatsby
+
+1. Open a terminal and make sure you are in the `./docs` folder with the correct version of Nodejs.
+2. Run `yarn upgrade:theme` (it's a custom script) to upgrade to the latest version of Gatsby.
+3. If you like, check your `yarn.lock` file in the git diff to make sure the theme is at the correct level.
+
+## Migration of Jekyll `./docs` site to Gatsby
+
+1. Delete the old Jekyll files:
+   - `Gemfile`
+   - `.gitignore` (The steps above include a new, better Gatsby .gitignore)
+   - `_config.yml`
+2. Move all remaining files into a temporary `ROOT/docs/OLD_JEKYLL` folder so that gatsby will ignore it for now. We do this because Jekyll allows you to use files in any location and it can be confusing to have them in the same folder as the new Gatsby files. We want to move them out of the way for now and then bring them back one-by-one as we fix them.
+2. One-by-one move each existing markdown files from the `ROOT/Docs/OLD_JEKYLL` folder into the `content/page` folder. It is recommended to make small git commits as you go so it's easier to see what changed and what broke the build. ***NEVER COMMIT ANYTHING BROKEN***
+   1. Change file extension from `*.md` to `*.mdx` 
+   2. Fix the frontmatter (see below).
+   3. Fix the markdown content by visiting the local page in the browser and looking for errors on the screen and in the console (common problems are listed below).
+   4. Move any images the page depends on from the `assets/images` folder to the `static/images` folder.
+
+
+## Typical problems and content migration gotchas:
+
+- Look for liquid tags that are left over from jekyll: `{{ some.liquid.tag }}` these need to be removed.
+- Any changes to `gatsby-config.ts` will require a restart of the dev server.
+- Unclosed img tags: `<img src="some-image.jpg">` is not allowed. You need to close the tag like this `<img src="some-image.jpg" />`
+- HTML Comments: `<!-- This is a comment -->` are not allowed and will break the site. You need to use MDX comments like this `{/* This is a comment */}`
+- Frontmatter Fields:
+    - All frontmatter is optional. You can have no frontmatter at all and the page will still work.
+    - `title` is optional. It is used in conjunction with `banner`
+    - `description` is optional. It is used in conjunction with `banner`
+    - If you have `isHome` set to true (you can ommit this completely if it's false) Then you need to wrap all your content in a container tag.
+    - If you want the banner at the top of the page set `banner:true`
+    - `banner` and `isHome` do not work well together
+    - `image`: This is the image that will be used for this page as a thumbnail in the lower image cards below the content.
+    - `imageAlt`: Related to the `image` field. This is the alt text for the image.
+
+```mdx
+import { Container } from '@mui/material'
+
+<Container maxWidth="xl">
+
+## This is a title
+
+here is some content
+
+</Container>
+```
+
+
+- Menu links: 
+    - **Broken menu links** (i.e. links that lead to a non-existent page) will not crash the site. They will just lead to a 404. On the 404 page you should be able to search for the correct url using the search form.
+- Images: 
+    - If you import images like `import WhatIsRiverscape from './what-is-riverscape.jpg'` then the image not being there WILL break the site. It will look like a red error in the console
+
+```
+  ModuleNotFoundError: Module not found: Error: Can't resolve './what-is-riverscape.jpg' in '/some/path/content/page'
+```