home documentation demo pages

content/page/api/index.mdx

@@ -0,0 +1,5 @@
+---
+title: Riverscapes API
+description: query and download data from the Riverscapes Data Exchange
+banner: true
+---

content/page/documentation/index.mdx

@@ -0,0 +1,122 @@
+---
+title: Documentation
+description: How to build and document a Riverscapes asset
+banner: true
+---
+
+The Riverscapes Consortium produces documentation for our tools and standards using websites like this one. These websites are written in [React](https://reactjs.org) using a plugin called [Gatsby](https://www.gatsbyjs.org/). This page is a guide for how to build and document a Riverscapes asset using this technology.
+
+## An Introduction to Gatsby
+
+Gatsby is a static site generator  that converts files written in [Markdown](https://www.markdownguide.org/) into a website. Gatsby is built on top of [React](https://reactjs.org/), a popular JavaScript library for building user interfaces. To build one of these websites you only need to be familiar with Markdown and React is optional. You write content in Markdown, push the changes to GitHub and the website is automatically built and published.
+
+## Hosting
+
+The Riverscapes Consortium hosts our software code and documentation websites on [GitHub](https://github.com/Riverscapes). We use GitHub Actions to automate the publishing of our Gatsby websites when we push the markdown to GitHub.
+
+## The Riverscapes Gatsby Theme
+
+We have published a [Riverscapes theme for Gatsby](https://github.com/Riverscapes/riverscapes-gatsby-theme) that can be consumed by consortium members for their documentation needs. See the the instructions below for how to use this theme.
+
+See the [demo page](./demo) for examples and instructions on how to use the Gatsby theme, what markdown elements to use and how to reference images etc.
+
+## New Riverscapes Gatsby Theme Site
+
+The following assumes that you want to host a Riverscapes documentation webiste inside a GitHub repository that already contains code for a Riverscapes tool, model or app. (As opposed to hosting a riverscapes themed site in an empty repository where the website is the only asset.)
+
+### Install NodeJS
+
+Visit the [NodeJS website](https://nodejs.org/en/) and install the latest LTS version of NodeJS. This is required to run Gatsby. You can accept the default settings during the installation process and you do not need to install any optional components (e.g. Chocolatey).
+
+Check the version of NodeJS that you have installed by opening a terminal and running the following command. You need to have at least version 16.
+
+```bash
+node --version
+```
+
+### Install Yarn  
+
+At the terminal run the following command to install Yarn.
+
+```bash
+npm install --global yarn
+```
+
+### Create a Gatsby site
+
+1. Create a new folder at the root of your repository called `docs`.
+1. Copy everything from the following location into your docs folder. Be sure to get everything including the hidden files (that start with a dot).`
+https://github.com/Riverscapes/riverscapes-gatsby-theme/tree/main/sites/template
+`
+1. 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.
+1. 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/sub-site, then change this to /sub-site NOTE: Case matters
+    - `start_url`: Should match the pathPrefix if you have one
+1. Open a terminal and make sure you are in the ./docs folder with the correct version of Nodejs
+1. Run `yarn install` inside the ./docs folder to install all the dependencies
+1. Run `yarn start` inside the ./docs folder to start the dev server and develop locally.
+1. Now move the 2 yml files from the folder `.github/workflows` into the root of your .git repo. (These files are the instructions to publish the site when the docs branched is pushed to GitHub)/
+1. At this point push the `docs` branch to GitHub.
+1. Go to the repository settings tab in GitHub and enable Github Pages
+
+Follow the steps in the next section to run the site locally and then push it to GitHub to publish it.
+
+## Running Gatsby Locally
+
+1. Open a terminal and make sure you are in the ./docs folder with the correct version of Nodejs (see above).
+1. Run `yarn start` to start the dev server and develop locally.
+1. Open a browser (if one doesn't pop-up automatically) and visit http://localhost:8000 to see the site.
+
+Note that you can make changes to markdown files (*.mdx), save the files and the site will automatically rebuild and refresh in the browser. This is called "hot reloading" and it's a great way to develop a site.
+
+However, any changes to the `gatsby-config.ts` file will require you to stop the dev server and restart it. This is because the `gatsby-config.ts` file is only read once when the server starts.
+
+## Publishing the Gatsby Site
+
+1. Save all your changes.
+1. Run the site locally to verify that it builds correctly (see previous section).
+1. Commit all your markdown changes to the `docs` branch.
+1. Push the `docs` branch to GitHub.
+1. Wait 3-5 minutes for it to build and deploy. You can monitor the progress of the build by visiting the Actions tab of your repository in GitHub.
+
+## Upgrading the Gatsby Theme
+
+These steps include making a git commit. It is recommended that you isolate the theme upgrade into a dedicated commit without any other content changes. Use a meaningful commit message like "Upgrading Gatsby theme". This is to help with troubleshooting if something goes wrong.
+
+1. Make sure that you have completed the Gatsby Setup steps above.
+1. Clone the repository that contains the documentation website and make sure that you are on the branch used to publish the site (typically `docs`).
+1.  Open a terminal and make sure you are in the ./docs folder with the correct version of Nodejs.
+1. Run `yarn upgrade:theme` (it's a custom script) to upgrade to the latest version of the Gatsby theme.
+1. It's a good idea to run the site locally to verify that the upgrade has worked correctly and that there are no negative side effects.
+1. Commit your changes and push them to GitHub. The GitHub actions will handle the publishing of the site. Wait 3-5 minutes and then check the live site.
+
+
+## Jekyll vs Gatsby
+
+In the past we used a different software tool called [Jekyll](https://jekyllrb.com/) to build our documentation websites. Jekyll is a static site generator like Gatsby. The two softwares are very similar in that they both convert markdown files into a website. However, Jekyll is written in Ruby and Gatsby is written in JavaScript. Jekyll is older and more mature but Gatsby is more modern and has a larger community of developers. We have decided to move to Gatsby because it is more flexible and easier to customize.
+
+The biggest difference is that in Gatsby you write files with the extension `*.mdx` instead of just *.md. The `x` stands for `jsx` which is a file extension used by React. This means that you can use React components inside your markdown files. This is a powerful feature that allows you to do things like embed interactive maps and charts inside your documentation.
+
+### Migrating a Jekyll site to Gatsby
+
+The following assumes that you have an existing GitHub repository with a `docs` folder that is being used to host your Jekyll site. 
+
+1. Clone the repository to your local machine.
+2. In git, make sure that you are currently at the head of the branch that is being used to publish the Jekyll site. This is typically caled `docs` and can be verified using the repository settings page.
+1. Delete the file called `Gemfile`.
+1. Delete the file called `.gitignore`.
+1. Delete the file called `_config.yml`.
+1. Create a new temporary branch for the Gatsby migration. Call it `gatsby-docs`.
+1. Create a new folder inside the `docs` folder called `OLD_JEKYLL`.
+1. Move all remaining files into a temporary `docs/OLD_JEKYLL` folder so that Gatsby will ignore them 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.
+Change file extension from *.md to *.mdx
+1. One-by-one move each existing markdown files from the `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. Fix the frontmatter (see below).
+    1. 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).
+    1. Move any images the page depends on from the assets/images folder to the static/images folder.
+1. With the markdown file in the correct location and the content fixed, you can now move the images from the `docs/OLD_JEKYLL` folder into the `static/images` folder.
+1. Once you have a site that runs locally (see above) you can commit your changes and push them to GitHub. The GitHub actions will handle the publishing of the site. Wait 3-5 minutes and then check the live site (see above).
+
+The goal is to slowly migrate all the old content to Gatsby *.mdx files and eventually delete the `docs/OLD_JEKYLL` folder. You can do this in small steps and commit your changes as you go. This will make it easier to see what changed and what broke the build.

content/page/index.mdx

@@ -1,30 +1,62 @@
 ---
 title: Home
-description: "Riverscapes website"
+description: "Riverscapes developer documentation"
 banner: true
 isHome: false
 ---
 
-Nostrud laborum enim tempor laboris officia deserunt ad dolor tempor velit cillum id et et. Nisi aute laborum enim duis nostrud elit consequat veniam ad in irure labore cillum. Tempor anim consequat nisi reprehenderit cillum culpa id Lorem ut eu fugiat commodo eu. Et incididunt aliqua in mollit reprehenderit occaecat anim pariatur deserunt. Occaecat labore dolor mollit fugiat. Enim est est esse enim ullamco.
-
-Excepteur velit id culpa amet. Ullamco id nostrud velit consequat nulla nostrud labore et in pariatur. Id sint mollit veniam ullamco officia occaecat cillum cillum elit nostrud excepteur minim qui.
-
-Adipisicing ex nostrud id et pariatur consectetur ea sit eu qui reprehenderit cillum cupidatat pariatur. Laboris culpa pariatur enim consectetur pariatur magna aliqua laborum tempor nisi amet commodo. Lorem sunt aute ea magna ea dolor mollit. Dolore cupidatat dolore irure qui commodo aliqua in. Qui labore duis sunt et adipisicing nulla. Enim Lorem duis eu ut exercitation.
-
-## Heading 1
-
-Lorem anim nisi tempor magna. Minim enim eiusmod in ex do aliqua adipisicing et commodo. Ea sunt excepteur adipisicing occaecat. Duis do laborum adipisicing sint laborum ea cillum voluptate. Qui labore enim officia ea. Ipsum incididunt pariatur in commodo veniam.
-
-### SubHeading 1
-
-In ad deserunt velit proident dolor amet elit cupidatat. Et ipsum magna enim cupidatat. Commodo qui sunt in non. Esse duis ex eu mollit est labore ad anim. Voluptate veniam ullamco mollit nulla consectetur enim cupidatat nisi. Amet sint mollit ullamco cillum duis voluptate.
-
-Ad irure laboris laboris minim. Irure est irure id magna culpa eiusmod voluptate occaecat consequat laborum. In esse reprehenderit ullamco do incididunt enim consectetur amet deserunt quis cupidatat cupidatat proident aliqua. Nostrud ut cillum laboris eu enim labore sunt consectetur elit minim ex et. Ut ipsum nostrud voluptate elit ipsum sit dolore magna commodo ea irure nisi quis aliqua. Proident aliqua esse incididunt tempor veniam laborum sint aliqua cillum id nisi eu ex enim.
-
-## Heading 2
-
-Eu tempor nostrud exercitation commodo amet sint nulla amet. Duis nostrud officia mollit et dolore magna minim aliquip duis id. Incididunt proident excepteur officia velit aute exercitation. Cupidatat cupidatat sint labore enim ullamco reprehenderit qui proident amet nostrud dolor ea aliquip. Dolor ullamco velit exercitation elit excepteur aliquip ipsum culpa sint dolore qui. Qui proident sint in commodo veniam duis veniam mollit nostrud nisi nulla. Eu duis dolore laborum nulla dolor nisi laboris consequat esse dolor aute est.
-
-Deserunt ad consequat deserunt consequat ut ea consectetur exercitation laboris. Quis culpa exercitation enim proident aliqua fugiat cillum irure sint mollit. Dolor sint laboris minim esse ea eu. Minim laborum proident reprehenderit veniam. Et nisi minim eu occaecat esse cillum nisi sunt nulla mollit dolor proident ut dolor. Ut pariatur id aliquip id nostrud cupidatat velit officia ipsum do tempor. Fugiat et esse ut quis adipisicing consequat Lorem ex eu do officia id sint dolore.
-
-Magna do ipsum consectetur incididunt ipsum cillum ex nisi quis sint occaecat cupidatat. Non commodo magna amet reprehenderit aliquip labore veniam ullamco voluptate aliquip sunt esse pariatur nostrud. Deserunt do dolor incididunt elit ad sit.
+import { Container } from '@mui/material'
+import CardImage from '/static/images/card-image.jpg'
+
+<Container maxWidth="xl">
+
+This website is the developer documentation for the [Riverscapes Consortium](https://riverscapes.net). You can learn about how we build tools and the datathey produce, as well as how you can contribute your own tools and data. 
+
+Use this web site learn to learn about the standards and documentation techniques required to collaborate with the Riverscapes Consortium.
+
+## Resources for Developers
+
+<Container maxWidth="xl">
+    <Grid container spacing={4} sx={{mt: 3}} padding={0}>
+      <StoryCard 
+        title="Standards & Compliance"
+        image={CardImage}
+        description="Learn about riverscapes standards and how to make your tools and data compliant."
+        to="/standards" />
+      <StoryCard 
+        title="Riverscapes API"
+        image={CardImage}
+        description="Learn how to use the Riverscapes API to access data."
+        to="/getting-started" />
+      <StoryCard 
+        title="Documentation"
+        image={CardImage}
+        description="Resources to build Riverscapes documentation and websites."
+        to="/documentation" />
+    </Grid>
+</Container>
+
+
+## Other Riverscapes Sites
+
+<Container maxWidth="xl">
+    <Grid container spacing={4} sx={{mt: 3}} padding={0}>
+      <StoryCard 
+        title="Riverscapes Consortium"
+        image={CardImage}
+        description="The Riverscapes Consortium main site."
+        to="/download/install" />
+      <StoryCard 
+        title="Our Tools"
+        image={CardImage}
+        description="Learn about each of our Riverscapes compliant tools."
+        to="https://tools.riverscapes.net" />
+      <StoryCard 
+        title="Data Exchange"
+        image={CardImage}
+        description="Discover and download Riverscapes compliant data."
+        to="https://data.riverscapes.net" />
+    </Grid>
+</Container>
+
+</Container>

content/page/standards/index.mdx

@@ -0,0 +1,5 @@
+---
+title: Standards
+description: Riverscapes standards and how to comply with them
+banner: true
+---

gatsby-config.ts

@@ -18,23 +18,29 @@ module.exports = {
     },
     menuLinks: [
       {
-        title: 'Menu Item 1',
-        url: '/other',
+        title: 'Standards',
+        url: '/standards',
+        items: [],
+      },
+      {
+        title: 'API',
+        url: '/api',
+        items: [],
+      },
+      {
+        title: 'Documentation',
+        url: '/documentation',
         items: [
           {
-            title: 'Submenu 1',
-            url: '/other',
+            title: 'Gatsby Instructions',
+            url: '/documentation',
           },
           {
-            title: 'Submenu 2',
-            url: '/other',
-          },
-        ],
-      },
-      {
-        title: 'StyleGuide',
-        url: '/demo',
-      },
+            title: 'Demo Page',
+            url: '/documentation/demo',
+          }
+        ]
+      }
     ],
   },
   plugins: [

package.json

@@ -23,7 +23,7 @@
     "format": "prettier --write \"**/*.{js,jsx,ts,tsx,json,md}\"",
     "start": "gatsby develop -p 8000 -o",
     "start:clean": "gatsby clean; gatsby develop -p 8000 -o",
-    "upgrade:theme": "yarn up @riverscapes/gatsby-theme",
+    "upgrade:theme": "yarn upgrade @riverscapes/gatsby-theme",
     "serve": "gatsby serve",
     "clean": "gatsby clean",
     "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1"