Demo & Styleguide

Demo Page where you can see how to do things

Gatsby special markdown syntaxs

Baked-in Components

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.

<HomepageCard />
<HomepageCardContent />
<HomepageCardHighlight />
<HomepageCardStat />
<Hero />

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.
<Youtube /> This is a helper since we use a lot of youtube videos. See examples below.
<Image /> This is a helper since we use a lot of images. 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. Use it instead of <div />
<Stack /> This is Mui's Stack component. Use it to space things evenly across the screen.
<Grid /> This is Mui's Grid component. 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. Use it to draw attention or anounce something.
That's all for now. We may add to this list as needed...

See the Advanced section below for more information on how to use MUI components.

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.

Import other MUI Components (sparingly)

This site is built on the Material UI 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:

Our markdown already translates to these components in many cases. Keeping the site as close to pure Markdown as possible keeps the site aligned to the styleguide. When you go rogue with components you can easily deviate from the styleguide.
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.
Context: Not all MUI components are designed to work inside the main content of the page.
Responsiveness: Not all components are responsive by default. Make sure you preview any changes on a phone or tablet before you commit them.
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 MUI components other than the ones that are baked in you must import them:

import { Container, Divider, Grid, Card, CardActionArea, CardMedia, CardContent, Typography } from '@mui/material'

<Divider />

Theme colors

The style we use has a number of preset colors that we can reference by name.

Use MUI Icons

Our theme has access to the Material UI Icons library. You can use them in markdown like this:

#### Use them on their own

<Icon iconName="Face" />
<Icon iconName="Face" color="primary"/>
<Icon iconName="Face" color="secondary"/>
<Icon iconName="Face" color="success"/>
<Icon iconName="FaceSpellBad" />

#### Use them in buttons too

<Button to="./demo" color="primary" iconName={"Face"} title="Icon found" />
<Button to="./demo" color="secondary" iconName={"FaceSpellBad"} title="With typo" />

Use them on their own

Use them in buttons too

Icon found

With typo

You can place icons inline as well Notice that when an icon isn't found you see with a tooltip.

Note about MUI icon names

Make sure to use the name exactly from the Material UI Icons library. Note that the names are case sensitive and DO NOT END WITH 'Icon'. For example, the icon Face is used like this: <Icon iconName="Face" /> NOT <Icon iconName="FaceIcon" />.

Don't Use ANY HTML tags!

While HTML tags like <a href="">, <ErrorUnclosed tagName="hr"><hr /></ErrorUnclosed> <b> etc... are technically allowed in markdown we recommend that you do not use them at all. They require a lot of extra work and styling to make them responsive and they are an anti-pattern to good markdown writing because they clutter up the content. Furthermore, this pattern now needs to be copied across pages and sites any time you nede it, snowballing the clutter to epic levels!

Alternatives in descending desirability:

Use the markdown equivalent whenever you can. This increases the maintainability of the site and reduces breakages during upgrade.
Find a baked-in component that does what you want. (That's why we created them).
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.
If there is absolutely no other way to do it then it might be best to check with a developer before proceeding.

Buttons

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="./demo">Regular button</Button> 

####  You can also the title attribute instead of putting the text in the child node
<Button to="./demo" title="Regular button" /> 

#### Different colors
<Button to="./demo" color="secondary" title="Secondary Color" />
<Button to="./demo" color="success" title="Success Color" />
<Button to="./demo" color="error" title="Error Color" />

####  You can also add a subtitle
<Button to="./demo" iconName="Face"
  title="This is a title"
  subtitle="This is a subtitle"
/>

#### With Mui Icons
<Button to="./demo" iconName="Face" title="MUI Icon button" /> 
<Button to="./demo" color="warning" iconName="Face_BAD" title="MUI Icon button (note misspelled icon)" /> 

#### With Image Icons
<Button to="./demo" imageSrc="/images/logo-nasa.png" title="Arbitrary image icon" /> 
<Button to="./demo" imageSrc="/images/logo-nasa_BAD.png" title="Arbitrary image icon"  subtitle="(note the broken link)" /> 

####  FullWidth

<Button to="./demo" title="Full Width Button" fullWidth/> 

#### External Link Button

<Button to="https://google.com">Google dot com</Button>

Regular button

External Link Button

Images

Internal images can come from several different places

Note: Do not use <StaticImage /> for markdown images. It will not work.

1. In the `static` folder (Prefered Method)

When you put images in the /static folder at the root of your site and reference them from there. You must use an absolute path for that.

Markdown/Remark syntax

Quick and dirty. Whenever possible please do images like this. they are not very configurable but they are guaranteed responsive on mobile and easy to maintain.

![DemoStatic](/images/demoStatic.jpg)

Image (instead of `<img />`)

If you need a bit more control you can use the <Image /> HTML syntax. You can use it the same as an <img /> tag with all the same attributes.

<Image src="/images/demoStatic.jpg" style={{opacity: 0.2, border: "20px solid orange"}} />

Linked images: Additionally you can include an to attribute to make the image a link. The properties of the to attribute are identical to the <Link /> compoent above (i.e. You can use relative or absolute paths.)
Image Captions: You can also include a caption attribute to add a caption to the image. This is useful for images that are not self-explanatory.

<Image src="/images/demoStatic.jpg" to="../about-us" caption="This is a simple caption" style={{border: "20px solid orange"}}/>

This is a simple caption

No Wrapping (advanced mode): You can add a noWrap attribute to remove all the fitting, centering and img wrapping. If you use this you will be left with the equivalent of a single unwrapped <img /> tag. As you can see though, this is not necessarily going to play nice with our theme. NOTE: IF YOU USE NOWRAP IT WILL IGNORE THE caption ATTRIBUTE.

<Image src="/images/demoStatic.jpg" to="../about-us" noWrap />

Float: You can add a float attribute to float the image to the left or right. This is useful for text wrapping.
- NOTE: Float is ignored if noWrap is used
- Floats are sometimes hard to work with and can be unpredictable. Headers (i.e. #, ##, ###), Dividers (---), and lists (*, 1., -) will clear the float.
- Floats will revert to full width on mobile screens.

<Image src="https://placekitten.com/200/300" to="https://google.com" float="left" caption="kitten pic" />
Velit nulla exercitation consectetur laborum elit magna ea non consectetur magna. Fugiat amet est voluptate consequat est commodo irure reprehenderit tempor pariatur adipisicing consequat aliquip. Labore proident veniam nulla officia dolor do. Nostrud adipisicing nisi aliquip magna sit aute velit labore nulla culpa cillum ex.

kitten pic

Velit nulla exercitation consectetur laborum elit magna ea non consectetur magna. Fugiat amet est voluptate consequat est commodo irure reprehenderit tempor pariatur adipisicing consequat aliquip. Labore proident veniam nulla officia dolor do. Nostrud adipisicing nisi aliquip magna sit aute velit labore nulla culpa cillum ex.

Caveats and notes:

<img /> doesn't work for this method either.

2. Relative to the `.mdx` file

Using a relative path to navigate relative to the mdx file (Note the dot slash ./ which means relative to the current path)

![DemoStatic](./demoRelative.jpg)

Caveats and notes:

<Image /> doesn't work with relative image paths.
<img /> doesn't work for this method either.

3. External Images

You can just use Markdown's Markdown/Remark syntax for external images:

![Kitten](https://placekitten.com/200/300)

Or if you need a bit more control you can use the <Image /> HTML syntax. You can use it the same as an <img /> tag with all the same attributes.

<Image src="https://placekitten.com/200/300" to="https://google.com" style={{opacity: 0.2, border: "20px solid orange"}} />

Caveats and notes:

DO NOT USE <img /> for this method either.

Markdown StyleGuide

## Headers

# H1 Header

## H2 Header

### H3 Header

#### H4 Header

##### H5 Header

###### H6 Header

> Blockquote Et ullamco dolor anim magna dolor aliquip enim consequat ut minim aliqua ea.

**Paragraph1** Veniam est [inline link](./demo) sit cillum anim ipsum velit culpa id veniam. Sint aute dolor excepteur eu commodo minim reprehenderit amet reprehenderit esse ea. Eu Lorem consectetur sint id aute ex cillum aliqua laborum aute deserunt ipsum. Deserunt ullamco Lorem deserunt commodo consequat magna ea id.

**Paragraph2** In amet excepteur non labore anim pariatur nostrud ad consequat quis nostrud ea ullamco occaecat. Ad mollit cillum occaecat est laborum eu. Nostrud quis officia cillum qui proident aliqua deserunt voluptate culpa ad dolor irure cupidatat esse. Qui nulla duis esse velit. Reprehenderit laboris labore ea do minim anim aliqua elit occaecat voluptate duis excepteur dolore est.

**Paragraph3** Elit labore aliquip exercitation dolor voluptate reprehenderit occaecat esse Lorem consectetur ad. Occaecat non esse velit in. Qui aute eu elit consectetur duis anim sunt cupidatat. Elit aliquip dolor ex commodo anim. Nulla Lorem sit et aute velit officia aute adipisicing. Adipisicing esse eiusmod nulla elit exercitation laborum. Consectetur cillum sint adipisicing laborum ex aute et dolor labore amet in in dolore.

* List item 1
* List item 2

1. List item 1
1. List item 2

| Header 1 | Header2  | Header 3   |
|--------------|------|---|
|Row1 Column1 | Row1 Column2 | Row1 Column3 |
|Row2 Column1 | Row2 Column2 | Row2 Column3 |
|Row3 Column1 | Row3 Column2 | Row3 Column3 |
|Row4 Column1 | Row4 Column2 | Row4 Column3 |

Headers

H1 Header

H2 Header

H3 Header

H4 Header

H5 Header

H6 Header

Blockquote Et ullamco dolor anim magna dolor aliquip enim consequat ut minim aliqua ea.

Paragraph1 Veniam est inline link sit cillum anim ipsum velit culpa id veniam. Sint aute dolor excepteur eu commodo minim reprehenderit amet reprehenderit esse ea. Eu Lorem consectetur sint id aute ex cillum aliqua laborum aute deserunt ipsum. Deserunt ullamco Lorem deserunt commodo consequat magna ea id.

Paragraph2 In amet excepteur non labore anim pariatur nostrud ad consequat quis nostrud ea ullamco occaecat. Ad mollit cillum occaecat est laborum eu. Nostrud quis officia cillum qui proident aliqua deserunt voluptate culpa ad dolor irure cupidatat esse. Qui nulla duis esse velit. Reprehenderit laboris labore ea do minim anim aliqua elit occaecat voluptate duis excepteur dolore est.

Paragraph3 Elit labore aliquip exercitation dolor voluptate reprehenderit occaecat esse Lorem consectetur ad. Occaecat non esse velit in. Qui aute eu elit consectetur duis anim sunt cupidatat. Elit aliquip dolor ex commodo anim. Nulla Lorem sit et aute velit officia aute adipisicing. Adipisicing esse eiusmod nulla elit exercitation laborum. Consectetur cillum sint adipisicing laborum ex aute et dolor labore amet in in dolore.

List item 1
List item 2

List item 1
List item 2

Header 1	Header2	Header 3
Row1 Column1	Row1 Column2	Row1 Column3
Row2 Column1	Row2 Column2	Row2 Column3
Row3 Column1	Row3 Column2	Row3 Column3
Row4 Column1	Row4 Column2	Row4 Column3

Youtube embeds

We have a custom component for youtube embedding. There is an optional caption attribute that will add a caption to the video.

<Youtube embedId="1hPxGmTGarM" caption="This is a simple caption" />

This is a simple caption

You can also embed using the <iframe /> from youtube but it's not as nice AND you should rename the attributes to be camelCase from frameborder to frameBorder and allowfullscreen to allowFullScreen or you get browser console warnings:

Code Blocks

In order to get good syntax highlighting you need to use the markdown code block syntax.

NOTE: the single quotes below SHOULD BE backticks. They are not single quotes.
I just can't use backticks in markdown because it will think I'm trying to
put a code block inside a code block.

'''languagename
<CODE HERE>
'''

Javascript example

#!/usr/bin/env node
const foo = 'bar'

function baz() {
  return foo
}

Python example

#!/usr/bin/env python3
a = 1
b = 2

def add(a, b):
  return a + b

Advanced

`noFrame` mode

Sometimes we need to render just the content of a page inside one of our tools. For this we simply add render=noFrame query param to the end of the URL. For example:

https://whatever.riverscapes.net/whatever/whatever?render=noFrame

This will strip out the sidebar, header and footer and allow the content to be rendered on its own.

Material UI (MUI)

MUI Core is a ReactJS implementation of Google's Material Design. It's a very powerful library and we use it extensively. It's also very well documented. You can find a lot of information on their site.

Do not use the <Container /> anywhere unless the isHome: true frontmatter is set or it will fight with the site's template and responsiveness.

Stack

<Stack /> This is Mui's Stack component. Use it to space things evenly either as a row or a column. This is preferable to <Grid /> for simple layouts.

Vertical Stack

<Stack spacing={2} border="2px solid red">
  <Box to="">Thing 1</Box>
  <Box to="">Thing 2</Box>
  <Box to="">Thing 3</Box>
</Stack>

Thing 1

Thing 2

Thing 3

Horizontal Stack

<Stack spacing={2} border="2px solid red" direction="row" justifyContent="center">
  <Box to="">Thing 1</Box>
  <Box to="">Thing 2</Box>
  <Box to="">Thing 3</Box>
</Stack>

Thing 1

Thing 2

Thing 3

Grids

Grids are useful for more complex layouts. They are not responsive by default so you need to use the xs, sm, md, lg, and xl props to make them responsive. You can also use the spacing prop to add space between the grid items. More information can be found here.

NOTE: Always try using <Stack /> before using <Grid />. It's much easier to use and is responsive by default.

<Grid container border="1px solid red">
  <Grid item xs={12} md={2} border="1px solid blue">Row1-Thing1</Grid>
  <Grid item xs={12} md={6} border="1px solid green">Row1-Thing2</Grid>
  <Grid item xs={12} md={4} border="1px solid yellow">Row1-Thing3</Grid>

  <Grid item xs={12} md={4} border="1px solid blue">Row2-Thing1</Grid>
  <Grid item xs={12} md={6} border="1px solid green">Row2-Thing2</Grid>
  <Grid item xs={12} md={2} border="1px solid yellow">Row2-Thing3</Grid>
</Grid>

Row1-Thing1

Row1-Thing2

Row1-Thing3

Row2-Thing1

Row2-Thing2

Row2-Thing3

Alert

Alert is a component that draws attention to something. It's useful for announcements or warnings. You can find more information here.

<Alert severity="info">
  This is an **info** alert — <strong>check it out!</strong>
</Alert>

This is an info alert — check it out!

<Alert severity="info" variant='filled'>
  This is an **info** alert with the **filled** variant — <strong>check it out!</strong>
</Alert>

This is an info alert with the filled variant — check it out!

<Alert severity="warning">
  This is an **warning** alert — <strong>check it out!</strong>
</Alert>

This is an warning alert — check it out!

<Alert severity="error">
  This is an **error** alert — <strong>check it out!</strong>
</Alert>

This is an error alert — check it out!

<Alert severity="success">
  This is an **success** alert — <strong>check it out!</strong>
</Alert>

This is an success alert — check it out!

Gatsby special markdown syntaxs

Baked-in Components

Custom Homepage Components:

Custom Components for buttons and links:

Material UI Components exposed by default:

Import other MUI Components (sparingly)

This should be done sparingly for a number of very good reasons:

Theme colors

Use MUI Icons

Use them on their own

Use them in buttons too

Note about MUI icon names

Don't Use ANY HTML tags!

Alternatives in descending desirability:

Links

Internal Links

Relative Internal Links

Absolute Internal Links

External Links

Buttons

Internal Links Button

You can also the title attribute instead of putting the text in the child node

Different colors

You can also add a subtitle

With Mui Icons

With Image Icons

FullWidth

External Link Button

Images

1. In the static folder (Prefered Method)

Markdown/Remark syntax

Image (instead of <img />)

Caveats and notes:

2. Relative to the .mdx file

Caveats and notes:

3. External Images

Caveats and notes:

Markdown StyleGuide

Headers

H1 Header

H2 Header

H3 Header

H4 Header

H5 Header

H6 Header

Youtube embeds

Code Blocks

Javascript example

Python example

Advanced

noFrame mode

Material UI (MUI)

Stack

Vertical Stack

Horizontal Stack

Grids

Alert

1. In the `static` folder (Prefered Method)

Image (instead of `<img />`)

2. Relative to the `.mdx` file

`noFrame` mode