updating the site

Riverscapes · Dec 12, 2023 · 736999c · 736999c
1 parent e9ddf6f
commit 736999c
Show file tree

Hide file tree

Showing 3 changed files with 82 additions and 57 deletions.
diff --git a/DeveloperWebsite.code-workspace b/DeveloperWebsite.code-workspace
@@ -14,13 +14,11 @@
     }    
   ],
   "settings": {
-    "window.title": "riverscapes.net GATSBY -${separator}${activeEditorShort}${separator}${rootName}",
-    "jest.disabledWorkspaceFolders": [
-      "📖 Docs",
-      "📱 App",
-      "🧬 Schema",
-      "🏠 Home",
-    ],
+    // 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",
@@ -32,49 +30,19 @@
       "source.fixAll.eslint": "explicit"
     },
     "files.watcherExclude": {
-      "**/node_modules/**": true
+      "**/node_modules/**": true,
+      "**/.cache/**": true
     },
     "search.exclude": {
       "**/node_modules/**": true,
+      "**/.cache/**": true,
+      "**/public/**": true,
       "**/dist/**": true,
     },
     "files.exclude": {
       "**/node_modules/**": true
     }
   },
-  "launch": {
-    "configurations": [
-      {
-        "type": "chrome",
-        "name": "Debug Using Chrome",
-        "request": "launch",
-        "url": "http://localhost:8000",
-        "sourceMaps": true,
-        "outFiles": [
-          "${workspaceFolder}/site/.cache/**", 
-          "${workspaceFolder}/site/public/**",
-          "${workspaceFolder}/theme/**",
-        ],
-      },
-      {
-        "type": "node",
-        "request": "launch",
-        "name": "Debug Gatsby Node API",
-        "console": "integratedTerminal",
-        "program": "${workspaceFolder}/node_modules/.bin/gatsby",
-        "runtimeExecutable": "${env:NVM_BIN}/node",
-        "args": ["develop"],
-        "sourceMaps": true,
-        "cwd": "${workspaceFolder}/site",
-        "outFiles": [
-          "${workspaceFolder}/site/.cache/**", 
-          "${workspaceFolder}/site/public/**",
-          "${workspaceFolder}/theme/**",
-        ],
-        "runtimeArgs": ["--inspect=9229"],
-      }
-    ]
-  },
   "extensions": {
     "recommendations": [
       "unifiedjs.vscode-mdx"

diff --git a/README.md b/README.md
@@ -2,12 +2,13 @@
 
 TODO: INSERT INSTRUCTIONS ON USING AND DEPLOYING
 
-- Run yarn install
-- Run yarn start
+- Run `yarn install`
+- Run `yarn start`
 
 ## Upgrading to latest theme
 
 because we have a custom theme and we have `"@riverscapes/gatsby-theme": "latest",`, we need to manually upgrade the theme.  To do this, run the following command:
 
 ```bash
 yarn up
+```
diff --git a/content/page/demo.mdx b/content/page/demo.mdx
@@ -5,41 +5,88 @@ description: "Demo Page where you can see how to do things"
 banner: true
 ---
 
+import FaceIcon from '@mui/icons-material/Face';
+
+
 # Gatsby special markdown syntaxs
 
 ## Baked-in Components
 
-Some components you can use without importing anything:
+Some components you can use without importing anything. This list will be updated as the theme grows.
+
+### Custom Homepage Components:
+
+These components were designed specifically for the Riverscapes homepage site and may not be that useful for derivative sites.
 
-* **Custom Homepage Components:**
   * `<HomepageCard />`
   * `<HomepageCardContent />`
   * `<HomepageCardHighlight />`
   * `<HomepageCardStat />`
   * `<Hero />`
-* **Custom Components for buttons and links:**
-  * `<Button />` This is `MuiButton` wrapped around the Gatsby Link component for navigation 
-  * `<Link />` This is Mui's `Link` component wrapped around Gatsby's Link component
-  * `<YoutubeEmbed />` This is a helper since we use a lot of youtube videos
-* **Material UI Components exposed by default:**
-  * `<Box />` This is [Mui's `Box` component](https://mui.com/material-ui/react-box/)
-  * `<Stack />` This is [Mui's `Stack` component](https://mui.com/material-ui/react-stack/)
-  * `<Grid />` This is [Mui's `Grid` component](https://mui.com/material-ui/components/grid/)
-  * `<Alert />` This is [Mui's `Alert` component](https://mui.com/material-ui/react-alert/)
 
+### Custom Components for buttons and links:
+
+  * `<Button />` This is `MuiButton` wrapped around the Gatsby Link component for navigation. See examples below.
+  * `<Link />` This is Mui's `Link` component wrapped around Gatsby's Link component. See examples below.
+  * `<YoutubeEmbed />` This is a helper since we use a lot of youtube videos. See examples below.
+
+### Material UI Components exposed by default:
 
+There are a few MUI components we expose by default that are relatively safe to use:
+
+  * `<Box />` This is [Mui's `Box` component](https://mui.com/material-ui/react-box/). Use it instead of `<div />`
+  * `<Stack />` This is [Mui's `Stack` component](https://mui.com/material-ui/react-stack/). Use it to space things evenly across the screen.
+  * `<Grid />` This is [Mui's `Grid` component](https://mui.com/material-ui/components/grid/). This is for more complex layouts and should be used carefully as it may not be mobile-compatible.
+  * `<Alert />` This is [Mui's `Alert` component](https://mui.com/material-ui/react-alert/). Use it to draw attention or anounce something.
+  * *That's all for now. We may add to this list as needed...*
 
 Using homepage elements on non-homepage pages may cause strange things to happen so use it carefully.
 
 As we continue to use and grow our sites we will likely add to this list.
 
-## Using MUI Components
+## Use MUI Components *(sparingly)*
+
+This site is built on the [Material UI](https://mui.com/) framework. For special cases we may need to use components that are not exposed by default. In order to do that we need to import them from the `@mui/material` package.
+
+#### This should be done sparingly for a number of very good reasons:
+
+1. **Maintainability**: The more components we use the more difficult it is to maintain the site. If MUI puts out a new patch that we decide to upgrade to the pure markdown components will not require ANY changes but the custom MUI components will all need to be re-tested across all our sites.
+1. **Context**: Not all MUI components are designed to work inside the main content of the page.
+2. **Responsiveness**: Not all components are responsive by default. Make sure you preview any changes on a phone or tablet before you commit them.
+3. **Modularity**: If you find yourself using the same pattern on multiple pages or multiple sites we should create a new `Baked-in` component for it. This will guarantee consistency across all our sites and make it easier to maintain.
+
+All of that said, if you absolutely need to use 
 
 ```typescript
 import { Container, Divider, Grid, Card, CardActionArea, CardMedia, CardContent, Typography } from '@mui/material'
 
 <Divider />
 ```
+## Use MUI Icons
+
+Our theme has access to the [Material UI Icons](https://mui.com/components/material-icons/) library. You can use them in markdown like this:
+
+<FaceIcon />
+<Button to='../about-us' color='error' endIcon={<FaceIcon />}>About us Button</Button>
+
+```typescript
+import FaceIcon from '@mui/icons-material/Face';
+<FaceIcon />
+<Button to='../about-us' color='error' endIcon={<FaceIcon />}>About us Button</Button>
+```
+
+## **Don't** Use HTML tags
+
+While HTML tags like are technically allowed in markdown we recommend that you do not use them at all. 
+
+#### Alternatives in descending desirability:
+
+1. Use the markdown equivalent whenever you can. This increases the maintainability of the site and reduces breakages during upgrade.
+2. Find a baked-in component that does what you want. (That's why we created them).
+3. Create a new baked-in component (or have a developer make one for you). This will mean you can use this new function across ALL sites with this theme.
+4. If there is absolutely no other way to do it then it might be best to check with a developer before proceeding.
+
+----------------
 
 ## Links
 
@@ -68,7 +115,7 @@ You can either use the markdown syntax or the `<Link />` component
 
 ### External Links
 
-External links operate the same way. By default, external links will open a new tab.
+External links operate the same way. Linking internally will navigate using the current browser tab and external links will open a new tab.
 
 * [Google](https://google.com) `[Google](https://google.com)`
 * <Link to='https://google.com'>Google</Link> `<Link to='https://google.com'>Google</Link>`
@@ -77,13 +124,22 @@ External links operate the same way. By default, external links will open a new
 
 ## Buttons
 
-Buttons are almost identical to links. By default, external links will open a new tab.
+Buttons are almost identical to links. Linking internally will navigate using the current browser tab and external links will open a new tab.
 
 ### Internal Links Button
 
+
 <Button to='../about-us'>About us Button</Button> 
+<Button to='../about-us' color='secondary'>About us Button</Button> 
+<Button to='../about-us' color='success'>About us Button</Button> 
+<Button to='../about-us' color='error'>About us Button</Button> 
+<Button to='../about-us' color='error' startIcon={<FaceIcon />}>About us Button</Button> 
+<Button to='../about-us' color='error' endIcon={<FaceIcon />}>About us Button</Button> 
 ```jsx
 <Button to='../about-us'>About us Button</Button>
+<Button to='../about-us' color='secondary'>About us Button</Button> 
+<Button to='../about-us' color='success'>About us Button</Button> 
+<Button to='../about-us' color='error'>About us Button</Button> 
 ```
 
 ### External Link Button