The Scientific sofTware Research for User experience, Design, Engagement, and Learning project (STRUDEL) is a planning framework and design system that empowers people to build effective user interfaces for scientific software.

strudel-web contains the code and content for the public-facing STRUDEL website. The code in this repo is deployed as the STRUDEL staging website. When ready for production, the Copy Build to Production Repo GitHub action copies the code over to the strudel-web-prod repo and deploys it to the production site.

• Staging Website
• Production Website

• Repo Overview
• Contributing and Deploying
• Creating and Editing Content
• Installing Locally
• About STRUDEL

This guide is for STRUDEL team members who have permission to create branches and run GitHub actions.

You can do this from the command line or from the github branches page. Make sure that you source the new branch from the latest version of the main branch by running the following from the main branch:

git pull origin main
git checkout -b update/my-new-branch

Update any markdown, config, or typescript files that you need to.

Request that changes from your branch get merged into the main branch.

If the PR thread indicates that there are not conflicts, then you are ready for step 6. If there are conflicts, first try to run the following from your update branch:

git merge origin main

(This may be equivalent to "Update your branch from main" if you are using a git GUI)

If you are not able to manage the conflicts, reach out for help before continuing 😄.

If there are no conflicts and you are ready, merge the PR into the main branch and delete the update branch you made for your changes.

Merging the PR should kick off the Deploy Gatsby Site to Pages workflow automatically. Check the status of that workflow on its actions page. Once the workflow completes, go to https://strudel.science/strudel-web and make sure your changes are there and that there were no unintended consequences.

NOTE: This process is still a work in progress. Right now, this will not replace any content on the official strudel.science site.

If the staging websites looks good, go to the actions page for the Copy Build to Production Repo workflow. Click the "Run workflow" dropdown, ensure that the main branch is selected, then click the "Run workflow" button. This will create build files for the website and copy them to the strudel-web-prod repo. This will automatically trigger a new deployment to the production website at https://strudel.science.

Go to the the production website at https://strudel.science and confirm that everything looks as expected.

You're done!

There are two possible ways that content gets loaded into the website:

1. Markdown (.mdx) files in the content directory
2. React page components in the src/pages directory

Files in the content directory can be used as source data for pages on the website. The subdirectories inside content are purely organizational and have no impact on the website, except for the images directory whose location gets referenced around the app.

The markdown files should all use the .mdx extension. MDX is a special kind of markdown file that can accept JSX code (e.g. React components, HTML) as well as regular markdown. Read more about MDX here.

For a markdown file to be turned into a page, you must add an id to the top of the file. To do this you use a YAML syntax called frontmatter which let's you add your own metadata to markdown files. For example, the comparison.mdx file in content/design-system/task-flows has the following at the top of the file:

---
id: 'task-flows-compare-data'
---

This is the syntax for adding metadata. Be sure to follow it exactly. The id can be any string value, but it is best to follow this convention for markdown pages: all lowercase kabob-case parent-section-filename.

To actually create a web page from the markdown file, you must add a page object to config/strudel-config.json. The strudel-config.json file determines the navigation links and structure that are rendered on the site as well as which markdown files are turned into pages.

If an object within the config's pages array has a markdownId, then the content of that page will be sourced from the markdown file in the content directory that has an id that matches the markdownId.

For example, take the following page object from strudel-config.json:

{
    "name": "Comparison",
    "path": "/design-system/task-flows/comparison",
    "markdownId": "task-flows-compare-data",
    "layoutComponent": "PageLayout"
},

This tells the sidebar menu to render a link to "/design-system/task-flows/comparison" with the text "Comparison". It also looks for a markdown file in the content directory that has id: task-flows-compare-data. The layoutComponent property is telling the app which layout component to use to wrap the markdown content in.

The path you supply to the object should be the full absolute path to the URL that should render the page.

The pages array in strudel-config.json is an ordered nested array. The top-level objects are rendered as links in the top Navbar. Children of top-level objects are rendered in the sidebar for their respective parent section. Children of second-level objects are rendered in a collapsible menu within the sidebar. The config only supports three levels of nesting for pages.

React component files in the pages directory are automatically recognized by Gatsby as pages in the website. The filename and subdirectory names are used to create the path name in the app router. For example, the file pages/about/team.tsx would be rendered at the path /about/team. If the filename is index.tsx, then it will be rendered at the root path of the directory it is in. For example pages/index.tsx is the home page of the app rendered at the path /.

Inside your .tsx file you can build a TypeScript React component just as you normally would. You can import other components, add functions, load data, or anything else. The only requirement is that you make the component the default export. Learn more about React here. Below is a minimal example of a page component:

import * as React from 'react';
import BaseLayout from '../../components/layouts/BaseLayout';

const TeamPage: React.FC = () => {
  return (
    <BaseLayout>
      <Typography variant="h1">My Team Page</Typography>
    </BaseLayout>
  );
};

export default TeamPage

This website is built with Gatsby, a React-based framework for building websites.

0. Prerequisites

   • NodeJS version 18+
   • NPM version 9+
   • Git version 2+

1. Clone the repo and install dependencies

   Clone the strudel repo onto your local machine.

   git clone [email protected]:strudel-science/strudel-web.git

   Navigate into the new strudel directory and install the dependencies.

   cd strudel-web
   npm install --legacy-peer-deps

   The --legacy-peer-deps flag is required any time you use npm install in this repo. This is because the gatsby-theme-material-ui library does not fully support gatsby 5.x.x yet, however there are currently no issues using them together.

2. Start developing.

   Start up the strudel site with gatsby.

   npm start

3. Open the code and start customizing!

   Your site is now running at http://localhost:8000!

   Edit src/pages/index.tsx to see your site update in real-time!

4. Learn more

   • Documentation
   • Tutorials
   • Guides
   • API Reference
   • Plugin Library
   • Cheat Sheet

If you don't see your change reflected right away, you may need to cancel the running process (ctrl + C) and restart the app (npm start).

If new packages have been added to the project since since your last merge, you will need to run npm install --legacy-peer-deps to install the new packages.

If you've made configuration changes you may also need to run npm run clean aka (gatsby clean) before restarting the app.

The Scientific sofTware Research for User experience, Design, Engagement, and Learning project (STRUDEL) is a planning framework and design system for scientific software towards improving the usability and user interfaces. It is funded by the Alfred P. Sloan Foundation and is based at the Lawrence Berkeley National Laboratory.

The STRUDEL team includes:

• Lavanya Ramakrishnan (PI)
• Rajshree Deshmukh
• Dan Gunter
• Drew Paine
• Sarah Poon
• Cody O'Donnell