Carberra Website

The repo for the Carberra website.

Table of Contents

• Tech Stack
  • Overview
  • Packages
  • Helpers
  • Storybook Addons
  • Markdown Plugins
• Structure
  • Source Structure
  • Public Structure
• Branches
• Development
  • Running Storybook
• Production
  • Running Next JS
  • Running Next JS (Automatically)
  • Running Plausible
    • First Time Only
    • Every Time
• Adding a New Series
  • Creating the Markdown File
  • Adding the Metadata
  • Adding Extra Information
  • Adding the Thumbnail
  • Full File Example
  • File Mapping
• Notes
• Questions

Tech Stack

This contains all of the information and specifics on the tech stack that the project uses.

Overview

Item	Value
Language	Typescript
Package Manager	Yarn
Server	Node.JS
Framework	Next JS (React)
Preview	Storybook
CSS Processor	PostCSS
Analytics/Stats	Plausible
API	Next JS API Routes

Packages

Name	Use
TailwindCSS	Styling from HTML via classes
Axios	API requests
Material UI (core, icons, and styles)	Nice, pre-made components to speed up development
Node Mailer	Send emails for contact form
React Markdown	Render markdown on pages
Gray Matter	Interpret and parse markdown files
SASS	Use SASS/SCSS for styling
Babel (core)	Part of Storybook

Helpers

Name	Use
Babel Loader	Part of storybook
SVGR/Webpack	Loading svgs via webpack
PostCSS Loader	Load PostCSS in Storybook
SASS Loader	Load SASS in Storybook
TSConfig Paths Webpack Plugin	Support TS path aliases in Storybook
Auto Prefixer	PostCSS plugin to add CSS prefixes
Tailwind Children (plugin)	TailwindCSS plugin to allow styling child components

Storybook Addons

Name	Use
Actions, Essentials, Links	Automatically installed with Storybook
PostCSS	Allow for loading of PostCSS
Builder, Manager (Webpack 5)	Use Webpack 5 to be consistent with main app
Theming	Add dark mode (essential)

Markdown Plugins

Name	Use
Remark GFM	Add GitHub style markdown support (such as tables)
Remark Slug	Add linking to markdown headers
Rehype Raw	Process HTML tags within markdown

Structure

Directory	Description
src	Main codebase
public	The files that are publicly accessable
scripts	Scripts to help with various related tasks

Source Structure

Directory	Description
pages	Source for pages
styles	Source for custom styling
ui	Source for ui components
stories	Source for storybook previews
_series	Source for series info pages
utils	Source for utility files

Public Structure

Directory	Description
brand	Holds brand assets
favicon	Holds favicon assets
assets	Holds general assets
assets/graphics	Holds graphics assets
assets/icons	Holds icon assets (mainly for home page)
assets/images	Holds image assets
assets/images/series	Holds thumbnails for series pages

Branches

Name	Description
master	What is running on the server — DON'T TOUCH
develop	Where changes/development occurs

Development

Instructions for development/getting a development enviornment setup.

• Make sure you have the correct Node.JS and Yarn versions installed.
• Run yarn in top folder to install packages from package.json.
• Start the development server by running yarn dev.
• Open http://localhost:3000 (dev server) in your browser.

Running Storybook

• Follow the above steps first
• Start storybook by running yarn storybook.
• Open http://localhost:6006 (storybook server) in your browser.

Production

To run the app in production, you will need to use docker and docker-compose to run both the Plausible server as well as the Next JS server. Folders for the servers should also be cloned into /var/www/.

Running Next JS

Run the following commands from the top folder (this one). Also, if another version is already running, make sure to stop that container first.

• Build docker image: docker build . -t carberra/website:<build version>
• Run docker image: docker run -p 127.0.0.1:3000:3000 --name carberra-website --rm -d carberra/website:<build version>

Running Next JS (Automatically)

To automatically build and deploy the docker container, all you have to do is create a new tag with the version number (such as 1.0.0) and then in the next 6-10m approx. it will have built the docker container, sent it to the server, stopped the old container, and started the new one on the server, automating the whole process of deploying a new version.

Running Plausible

Run the following commands from the Plausible hosting folder (the one cloned below).

First Time Only

• Clone hosting repo: git clone https://github.com/plausible/hosting plausible
• Fill in info in plausible-conf.env (admin creds, etc).
  • Generate secket key to put in SECRET_KEY_BASE by running openssl rand -base64 64
• Run the commands below under the every time header
• Verify all users: docker exec plausible_plausible_db_1 psql -U postgres -d plausible_db -c "UPDATE users SET email_verified = true;"

Every time

• Build and start required images: docker-compose up -d

Backup Site

You will find a very simple backup site in the html directory. This is meant to function as a backup in case for some reason the docker container isn't running or accessable. To do so, just setup the nginx config to send to the index.html in that directory as the backup page and you will be good to go.

Adding a New Series

To add a new series, you just need to create a markdown file for the series with the information required as well as any other information you want to include and place the thumbnail in the correct location.

Creating the Markdown File

Create a new markdown file in the _series directory, with the name being what the url will be. So if the file is named how-to-python.md, the url will be how-to-python.

Adding the Metadata

Then, you need to enter the metadata at the top of the file, which is used to construct the page and card, following the template below.

---
title: 'TITLE'
tagline: >
  TAGLINE
thumbnail: '/assets/images/series/THUMBNAIL.jpg'
launch_date: 'DATE (YYYY-MM-DD)'
last_updated: 'DATE (YYYY-MM-DD)'
status: 'STATUS (ACTIVE, DORMANT, OR DEAD)'
playlist_link: 'https://www.youtube.com/playlist?list=PLAYLIST_ID'
---

An example of what this metadata should look like is shown below.

---
title: 'How to Python'
tagline: >
  Ever wanted to get into Python, or even programming as a whole, but didn't know where to start? This playlist might be just for you.
thumbnail: '/assets/images/series/how-to-python.jpg'
launch_date: '2020-11-30'
last_updated: '2022-06-10'
status: 'Active'
playlist_link: 'https://www.youtube.com/playlist?list=PLYeOw6sTSy6bHRFwzIA3VAy05J2tJAAoS'
---

This information is used to create the series card as well as the top part of the series info page.

Adding Extra Information

After that, you can add any extra information that you want (such as requirements, notes, etc.) on the page below the metadata area in markdown. This extra information will be rendered below the info section on the series info page.

Adding the Thumbnail

Upload the thumbnail in jpg format to the folder for thumbnails, found at assets/images/series/, ideally naming it the same name as the corresponding markdown file. So if the markdown file was how-to-python.md, then the thumbnail file should be how-to-python.jpg. Then link to that file in the thumbnail metadata area in the markdown file and you are good to go.

Full File Example

---
title: 'How to Python'
tagline: >
  Ever wanted to get into Python, or even programming as a whole, but didn't know where to start? This playlist might be just for you.
thumbnail: '/assets/images/series/how-to-python.jpg'
launch_date: '2020-11-30'
last_updated: '2022-06-10'
status: 'Active'
playlist_link: 'https://www.youtube.com/playlist?list=PLYeOw6sTSy6bHRFwzIA3VAy05J2tJAAoS'
---

## Required

- Python 3.10.2 or higher

## Optional

- WSL

## Notes

This is a beginner series. If you are not a beginner, most of this will probably cover items you already know. I would suggest skipping ahead to later intermediate or hard episodes of the series if you would like to watch.

File Mapping

Notes

• Favicon files generated using realfavicongenerator.net

Questions

If there are any questions, please get in contact with Parafoxia or MrDogeBro for help.