Skip to content

Latest commit

 

History

History
247 lines (171 loc) · 6.97 KB

DEVELOPER_NOTES.md

File metadata and controls

247 lines (171 loc) · 6.97 KB

Installation

This website is built with Gatsby, a static site generator with Markdown-based websites and a rich ecosystem of plugins.

Directory Overview

$ tree -L 1
.
├── assets              # Website assets: favicon, logo, etc.
├── CHANGELOG.md
├── content             # Markdown/webpage 'home'
├── gatsby-config.js    # Sitewide configuration file
├── INSTALLATION.md
├── package.json        # Website dependencies: uses Yarn to install
├── README.md
├── src                 # Theme & custom components source files
├── static              # static files: PDFs, BibTeX, etc.
└── yarn.lock           # Locks dependencies to specific version

Installing Dependencies

Instructions sourced from the Gatsby documentation.
# Upgrade apt
$ sudo apt update
$ sudo apt -y upgrade
$ sudo apt-get install -y curl git

# Install NVM
$ curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.1/install.sh | bash
$ nvm install 14
$ nvm use 14

# Check versions
$ nvm --version
$ node --version
$ npm --version

Installing Gatsby

$ npm install -g gatsby-cli
$ gatsby --version
$ gatsby --help

Compiling the website

Development Version

Gatsby has a development mode which allows for live previewing and change monitoring. To run,

$ gatsby develop

The console will show output similar to:

You can now view gatsby-starter-flex in the
browser.
⠀
  http://localhost:8000/
⠀
View GraphiQL, an in-browser IDE, to explore your
site's data and schema
⠀
  http://localhost:8000/___graphql

Navigate to http://localhost:8000/ to view the website.

Production Version

To build the production version, run:

$ gatsby build

Note that content may not render correctly when viewing these built files locally. This is due to how relative/absolute URLs are generated by Gatsby - viewing them on an actual web server is the best way to verify content, outside of gatsby develop.

Deploying to GitHub Pages

The configured GitHub Action should automatically deploy changes to the gh-pages branch.

Developer Notes

Rendering in VS Code

Visual Studio Code has a plugin called Live Preview which simplifies web development. After installing the plugin, open the packages pane (on Mac: ⌘ + shift + P) and launch Live Preview: Start Server.

Adding New Pages

Existing pages can be found under ./content/pages/, and take the form page-name/index.mdx. MDX is an extension of Markdown with support for React.js components.

For more information, see:

Comprehensive Developer Notes

Running | Dev Notes | Components | Help

Running

To test locally, run:

yarn install

to install any dependencies, and

gatsby develop

to launch the server.

A localhost server will be started with live updates as pages and components change. The server must be restarted if gatsby-config.js changes.

If dependencies change, yarn.lock and package.json must have their updates pushed to the repo as well.

Testing Deployment

To test how CI will behave, run

rm -rf node_modules/ && yarn install && yarn deploy

Changing Repos

Before deploying to a web hosting service, the pathPrefix variable needs to be updated relative to the deployed websites location.

I.e., for https://amanzi.github.io/landing-page-test, the pathPrefix will be landing-page-test.

For https://amanzi.github.io/, pathPrefix will be /.

This variable is located in gatsby-config.js.

Developer Notes

Adding Pages

Every Markdown file under content/pages will be compiled into a web page. See other pages in that directory to get an idea of how these pages should be formatted.

An example page might be:

---
title: Example Markdown Page
excerpt: ok
---

<Section 
  heading="Example Markdown Page"
  lead="Tristique ipsum tempor eget"
>
<Div style={{
  maxWidth: ["none", "none", "60%"]
}}>

# Markdown Stuff

### Here, I can add Markdown components.

One should add images like this to take advantage of Gatsby features:

<Image src="placeholder.jpg" style={{mt: [4,8]}}/>

Though the regular syntax of `![alt](url)` will still work.

### Another Subsection

Remember to close the Div and Section blocks when you're done.
We have these to ensure consistent formatting (i.e., centering, body div width).

</Div>
</Section>

Components

  • Custom components are found under src/*.js, and the gallery component is found under src/components/gallery.js.
    • These components can be changed at will.
    • The theme components can be overridden: e.g., the footer

Theming

Assets

  • All assets (videos, BibTex files, etc) should go under static

Images

  • All images should go under assets/images, except those being used in a photo gallery.
  • Photo gallery images go under static/photo-gallery.
  • Photo gallery images will also need a thumbnail image to improve loading times.
    • Thumbnails can easily be created with the mogrify command:
      • mogrify -resize 300 *.png
      • Installed using brew install imagemagick

Videos

Videos and video thumbnails are found under static/video-gallery.

  • Videos must be in MP4 format

    • FFMPEG can be used for conversion:
      • ffmpeg -i ${INPUT} -vcodec h264 -acodec mp2 -b:a 32k -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" ${EXPORT}

  • Videos require a thumbnail image as well

    • This is displayed when the video hasn't started loading yet
    • FFMPEG can also create thumbnail images:
      • This command can be used to easily create thumbnails:
        • ffmpeg -i ${INPUT_VIDEO} -vf "thumbnail" -frames:v 1 ${OUT_IMAGE}

Help

In general, this should be pretty straightforward to add new pages and edit content.

However, Gatsby.js and React.js have some small "gotchas" for those not familiar with them. Please open an issue or email me if you're having difficulties. 99 times of 100, the solution will be straightforward yet hidden from those without intimate knowledge of React.