Technical

This website is hosted for free by GitHub Pages which is a static site hosting solution. The scaffolding for this site is based on Docusaurus Version 2.0 which takes Markdown and JavaScript files and generates static HTML.

Please direct questions about the technical underpinnings of this site to Brandon Budnicki.

GIT Training

If you are not familiar with GIT we recommend playing Learn Git Branching to learn the fundamentals in an interactive way (2 hours). Additionally the The GitHub GIT Cheat Sheet covers common commands (20 minutes)

Main file types

• Markdown - Docusaurus version
  • .md which is plain markdown
  • .mdx which is used for markdown and adds additional processing to allow importing JavaScript
• JavaScript
  • .js used for ReactJS components or special pages that require additional styling
• JSON
  • .json used to store raw data

Folder Structure

The site follows the same standard Docusaurus structure.

/root
    /blog           - news & articles specific to PPSR core
    /docs           - .md and .mdx pages that contain the standard. These get versioned!
    /src
        /pages      - special pages like the homepage
        /components - ReactJS components
    /static/json    - JSON Schema files

---

Running Locally

This software can be run locally on your machine for testing purposes or creating larger changes. This will work on Windows, OSX, or Linux. The process is described in Docusaurus Installation except that you will be using an existing GitHub repository instead of "scaffolding" a new one.

Prerequisite Software

Required

These requirements are the same for all Docusaurus sites

• GIT-SCM to clone, merge, and submit pull requests. To check for this software run this command from the terminal

    git --version
  

• NPM Version > 10.15.1 to build the software and run locally. To check for this software run this command from the terminal

    node -v
  

• A plaintext editor for exiting files. Do not use Microsoft Word Ses below for recommendation

Recommended

We recommend the following additional tools to aid in content editing & ease of use. Install these if you are not experienced with software development, they will make your life easier.

• Visual Studio Code a plain text editor and development environment available for free on Windows, OSx, or Linux
• GitHub Desktop a friendly user interface for GIT-SCM
• GitLens a GitHub management extension for VS Code.
• Code Spell Checker extension for VS Code

Step by Step

After installing the Prerequisite Software:

1. Clone the repository from github.com/citizen-science-association/ppsr-core using the command line or GitHub Desktop

   git clone https://github.com/citizen-science-association/ppsr-core.git
   

2. Install dependencies: Open a terminal / command line in the root folder of your repository

   npm install
   

3. Run local build server: Open a terminal / command line in the root folder of your repository

   npm run start
   

4. Your browser should automatically open to http://localhost:3000/

info

Any changes you save will immediately cause the page to refresh and be visible

---

Publishing Process

After all changes have been merged into the master branch, the publishing process can being. This follows the standard deployment process for Docusaurus, specifically for the GitHub pages process.

Use this command to deploy to the live site.

GIT_USER=<GITHUB_USERNAME> npm run deploy

cmd /C "set GIT_USER=<GITHUB_USERNAME>&& npm run deploy"

info

Changes should appear within 2 minutes. Be sure to do a hard refresh of the page, locally cache files from the public site might show the old site.