From b2db8da36d734d97c7b34c1f40a2eb645ec2853c Mon Sep 17 00:00:00 2001 From: James Kerrane Date: Mon, 4 Dec 2023 09:25:47 -0700 Subject: [PATCH 1/2] Start work on splash message tutorial --- .../tutorials/how-to-add-splash-message.mdx | 101 ++++++++++++ sidebars.js | 4 + src/components/Countdown/index.tsx | 147 ------------------ src/components/Countdown/styles.module.css | 34 ---- src/components/Splash/index.tsx | 38 +++++ src/pages/index.tsx | 15 +- 6 files changed, 155 insertions(+), 184 deletions(-) create mode 100644 docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx delete mode 100644 src/components/Countdown/index.tsx delete mode 100644 src/components/Countdown/styles.module.css create mode 100644 src/components/Splash/index.tsx diff --git a/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx b/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx new file mode 100644 index 0000000..db0f9a2 --- /dev/null +++ b/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx @@ -0,0 +1,101 @@ +import Admonition from '@theme/Admonition'; + +# Tutorial: How to add a splash message to the site + +:::info + +To use all of the tools in this guide, you will need to be 13-years of age or older due to the terms of use of a software tool you will use, [GitHub](https://docs.github.com/en/site-policy/github-terms/github-terms-of-service). If you are under 13-years of age, please email me at [jpkerrane01@bvsd.org](mailto:jpkerrane01@bvsd.org) and we can adjust these steps so you can contribute! + +::: + +Hello there! In this tutorial, you will learn step-by-step how to add a "Splash" message to the homepage on the [homepage](https://theorybear.org). + +You will learn how to: +* Contribute to a [open-source software project](https://en.wikipedia.org/wiki/Open-source_software_development) +* Use distributed version control tools like Git, GitHub, and pull requests +* Create a remote development environment + +This guide does not assume any prior software development experience. + +## Step 1: Create a development environment + +### How the site works +This site is made with [React](https://react.dev/), a [JavaScript library](https://en.wikipedia.org/wiki/JavaScript_library) that helps in building user interfaces for websites or web applications. + +You don't need to know how React works for this tutorial, but the more you know the more of the site's code that you will understand! + +If you want to dig deeper into how this site works, the following are free tutorials that will take you from zero-knowledge to a pro! + +* If you are unfamiliar with web dvelopment (HTML, CSS), check out [freeCodeCamp's Responsive Web Design Certification](https://www.freecodecamp.org/learn/2022/responsive-web-design/). +* If you are unfamiliar with JavaScript, check out [freeCodeCamp's JavaScript Algorithms and Data Structures Certification](https://www.freecodecamp.org/learn/javascript-algorithms-and-data-structures/). +* If you are familiar with JavaScript, check out the [React Quick Start tutorial](https://react.dev/learn) or [freeCodeCamp's Front End Development Libraries Certification](https://www.freecodecamp.org/learn/front-end-development-libraries/). + +### How we use React + +In conjunction with React, we use a site generator called [Docusarus](https://docusaurus.io/). This is a program that takes input like React-specific files ([.jsx](https://react.dev/learn#writing-markup-with-jsx), [.tsx](https://react.dev/learn/typescript), [.mdx](https://mdxjs.com/)), regular web development files (.html, .css, .js), and text files ([.md](https://www.markdownguide.org/)), to turn into efficient website code! + + +### Finding the site's source code + +This site is [open-source](https://en.wikipedia.org/wiki/Open_source), which means that all of the code that makes it function is published for anyone to view. + +We publish our site's code to GitHub, a code repository that hosts the source code of countless open source projects, at https://github.com/thatrobotdev/theorybear. + +Here is a brief explanation of the structure of the site: + +* blog/ – The folder that holds everything that goes on [theorybear's blog](/blog). +* docs/ – The folder that holds all of the music theory content (including this page)! +* src/ – The folder that holds site code (React components, CSS, complicated pages like the homepage) +* static/ – The folder that holds site images and other assets +* docusaurus.config.js – Main configuration file for the site +* sidebars.js – File that holds information on how the site's sidebar menu should organize links + +Try finding where a specific part of the site is implemented in the code, and see how it is implemented! + +### Creating an editable version of the site + +Now that you have taken a look at the site's structure, it's time to create an "editable" version of the site, or a development environment. + +This will allow you to edit the source code of the site and see a preview of how the site would change with your edit! + +You can either create a local or remote development environment, with different pros/cons of each: + +**Local development environment** +Most common type of development environment, runs on your computer. You are required to download all of the tools that make a website work. Great for working without internet, working with your preferred text editor/development tools. + +**Remote development environment** +Gaining in popularity, runs on someone else's computer. This computer can be standardized so the tools you need can be automatically downloaded. If you mess the development environment up, it's easy to reset and undo changes. + +For this tutorial, we will be using GitHub Codespaces, a remote development environment that allows you to edit code in your web browser using a modified version of the [Visual Studio Code editor](https://code.visualstudio.com/). + +1. Go to the site's source code at https://github.com/thatrobotdev/theorybear +2. Click the green "Code" button, and navigate to the "Codespaces" tab. +3. Sign in/Create a new GitHub account. +4. Click "Create codespace" + +You should now be able to see a copy of the website in your web browser that you can navigate through in the explore window. Clicking on a file in the left bar will allow you to edit it. + +5. In the bottom window, in the terminal, type in the following command and hit ENTER: + +`npm run start` + +This command uses the [package manager](https://en.wikipedia.org/wiki/Package_manager) [npm](https://www.npmjs.com/) to download all of the tools that the site needs to build the website from the source code. + +6. (window opens) + +7. Now it's time to add the splash message! In the left window file explorer, navigate to `src/components/Splash/index.tsx`. Find the code that looks like this: + +```js +let splashMessages = [ + ["You've got this!", "JP"], + ["Need more cowbell!", "JP"], + ["Beary fun music theory ;)", "JP"], + ["Every Good Bear Does Fine", "JP"], + ["FACE!!!!!", "JP"], + ["Arctic Cubs Explore Glaciers :)", "JP"] +]; +``` + +This is the code that the website randomizes to display a splash message. + +The first string in the JavaScript array is the message, and the second string is the attribution. \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index 5abb151..a16caad 100644 --- a/sidebars.js +++ b/sidebars.js @@ -251,6 +251,10 @@ const sidebars = { howToContribute: [ "how-to-contribute/overview", "how-to-contribute/tri-m", + { + type: "autogenerated", + dirName: "how-to-contribute/tutorials" + } ], }; diff --git a/src/components/Countdown/index.tsx b/src/components/Countdown/index.tsx deleted file mode 100644 index 00fee02..0000000 --- a/src/components/Countdown/index.tsx +++ /dev/null @@ -1,147 +0,0 @@ -import React from 'react'; -import styles from './styles.module.css'; -import Link from '@docusaurus/Link'; - -const today = new Date(); - -type TestDate = { - number: Number; - date: Date; -}; - -const PumaPrideTestDates: TestDate[] = [ - { - number: 1, - date: new Date('2023-10-06'), - } -]; - -const PhoenixFireTestDates: TestDate[] = [ - { - number: 1, - date: new Date('2023-10-06'), - } -]; - -const ConcertChoirTestDates: TestDate[] = [ - { - number: 1, - date: new Date('2023-10-13'), - } -]; - -function closestEventDate(testDates: TestDate[]): TestDate { - let closestEventDate: Date; - let closestEventNumber: Number; - - for(let i = 0; i < testDates.length; i++) { - // Upcoming event must be after today - if(testDates[i].date > today) { - // If closestEvent is undefined, set it to the current event - if(typeof closestEventDate == 'undefined') { - closestEventDate = testDates[i].date; - closestEventNumber = testDates[i].number; - } else if(testDates[i].date < closestEventDate) { - // If closestEvent is defined, check if the current event is closer than the previous closest event - - // If it is, set closestEvent to the current event - closestEventDate = testDates[i].date; - closestEventNumber = testDates[i].number; - } - } - } - - const closestTest: TestDate = { - date: closestEventDate, - number: closestEventNumber, - }; - - return(closestTest); -} - -export default function Countdown(): JSX.Element { - const closestPumaPrideTest: TestDate = closestEventDate(PumaPrideTestDates); - const closestConcertChoirTest: TestDate = closestEventDate(ConcertChoirTestDates); - const closestPhoenixFireTest: TestDate = closestEventDate(PhoenixFireTestDates); - - let bearMessage = "Congratulations to 128 Grazer!"; - let daysUntilPumaPrideTest: number - let daysUntilConcertChoirTest: number; - let daysUntilPhoenixFireTest: number; - - if (closestPumaPrideTest.date != undefined) { - daysUntilPumaPrideTest = Math.ceil( - (closestPumaPrideTest.date.getTime() - today.getTime()) / - (1000 * 60 * 60 * 24) - ); - - bearMessage += ` Puma Pride: Your music theory test ${closestConcertChoirTest.number} is in ${daysUntilPumaPrideTest} day`; - if (daysUntilPumaPrideTest > 1 || daysUntilPumaPrideTest == 0) { - bearMessage += "s"; - } - bearMessage += "!"; - - } - - if (closestConcertChoirTest.date != undefined) { - daysUntilConcertChoirTest = Math.ceil( - (closestConcertChoirTest.date.getTime() - today.getTime()) / - (1000 * 60 * 60 * 24) - ); - - bearMessage += ` Concert Choir: Your music theory test ${closestConcertChoirTest.number} is in ${daysUntilConcertChoirTest} day`; - if (daysUntilConcertChoirTest > 1 || daysUntilConcertChoirTest == 0) { - bearMessage += "s"; - } - bearMessage += "!"; - } - - if (closestPhoenixFireTest.date != undefined) { - daysUntilPhoenixFireTest = Math.ceil( - (closestPhoenixFireTest.date.getTime() - today.getTime()) / - (1000 * 60 * 60 * 24) - ); - - bearMessage += ` Phoenix Fire: Your music theory test ${closestPhoenixFireTest.number} is in ${daysUntilPhoenixFireTest} day`; - } - - if (closestPumaPrideTest.date != undefined && closestConcertChoirTest.date != undefined && closestPhoenixFireTest.date != undefined) { - if (daysUntilPumaPrideTest == daysUntilConcertChoirTest && daysUntilPumaPrideTest == daysUntilPhoenixFireTest) { - bearMessage += ` You have a music theory test in ${daysUntilPumaPrideTest} day`; - - if (daysUntilPumaPrideTest > 1 || daysUntilPumaPrideTest == 0) { - bearMessage += "s"; - } - - bearMessage += "!"; - } - } - - const buttonLink = "https://theorybear.org/docs/introduction"; - let buttonMessage = "Let's get studying!"; - //buttonMessage = "Brush up on some skills"; - - return ( -
- -
-
-
- Countdown -
-
-

{bearMessage.toString()}

-
- - {buttonMessage.toString()} - -
-
-
- -
-
- ); -} \ No newline at end of file diff --git a/src/components/Countdown/styles.module.css b/src/components/Countdown/styles.module.css deleted file mode 100644 index 146e90d..0000000 --- a/src/components/Countdown/styles.module.css +++ /dev/null @@ -1,34 +0,0 @@ -.features { - display: flex; - align-items: center; - padding: 2rem 0; - width: 100%; -} - -.featureSvg { - height: 200px; - width: 200px; -} - -/* Typewriter effect from https://www.sitepoint.com/css-typewriter-effect/ by Matt Nikonorov */ - -.typedOut { - overflow: hidden; - border-right: .15em solid brown; - border-radius: 0px; - white-space: nowrap; - animation: - typing 1s steps(20, end) forwards, - blinking 1.2s infinite; - width: 0; -} - -@keyframes typing { - from { width: 0 } - to { width: 100% } -} - -@keyframes blinking { - from { border-color: transparent } - to { border-color: brown; } -} \ No newline at end of file diff --git a/src/components/Splash/index.tsx b/src/components/Splash/index.tsx new file mode 100644 index 0000000..dc2fac3 --- /dev/null +++ b/src/components/Splash/index.tsx @@ -0,0 +1,38 @@ +import React from 'react'; +import Link from '@docusaurus/Link'; + +export default function Splash(): JSX.Element { + +let splashMessages = [ + ["You've got this!", "JP"], + ["Need more cowbell!", "JP"], + ["Beary fun music theory ;)", "JP"], + ["Every Good Bear Does Fine", "JP"], + ["FACE!!!!!", "JP"], + ["Arctic Cubs Explore Glaciers :)", "JP"] +]; + +var randomSplash = Math.floor(Math.random() * splashMessages.length); + + return ( +
+
+
+
+ Countdown +
+
+

{splashMessages[randomSplash][0]}

+

+ + + Submitted by {splashMessages[randomSplash][1]} + + +

+
+
+
+
+ ); +} \ No newline at end of file diff --git a/src/pages/index.tsx b/src/pages/index.tsx index f228e3e..d38c68a 100644 --- a/src/pages/index.tsx +++ b/src/pages/index.tsx @@ -2,16 +2,17 @@ import React from 'react'; import clsx from 'clsx'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import Layout from '@theme/Layout'; +import Link from "@docusaurus/Link"; import Alert from '@site/src/components/Alert'; import JpsCorner from '@site/src/components/JPsCorner'; -import Countdown from '@site/src/components/Countdown'; +import Splash from '@site/src/components/Splash'; import styles from './index.module.css'; function HomepageHeader() { const {siteConfig} = useDocusaurusContext(); return ( -
+
@@ -19,7 +20,15 @@ function HomepageHeader() {

{siteConfig.tagline}

- + +
+ + {"Let's get studying!"} + +
From 6516ee2173ed61ae90f91df68b504ebef9e21528 Mon Sep 17 00:00:00 2001 From: James Kerrane Date: Fri, 8 Dec 2023 08:51:50 -0700 Subject: [PATCH 2/2] Finish splash message tutorial --- .../tutorials/how-to-add-splash-message.mdx | 119 +++++++++--------- 1 file changed, 57 insertions(+), 62 deletions(-) diff --git a/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx b/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx index db0f9a2..884f768 100644 --- a/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx +++ b/docs/how-to-contribute/tutorials/how-to-add-splash-message.mdx @@ -8,82 +8,40 @@ To use all of the tools in this guide, you will need to be 13-years of age or ol ::: -Hello there! In this tutorial, you will learn step-by-step how to add a "Splash" message to the homepage on the [homepage](https://theorybear.org). +Hello there! In this tutorial, you will learn step-by-step how to add a "Splash" message to the homepage on the [homepage](https://theorybear.org) using GitHub codespaces. -You will learn how to: -* Contribute to a [open-source software project](https://en.wikipedia.org/wiki/Open-source_software_development) -* Use distributed version control tools like Git, GitHub, and pull requests -* Create a remote development environment +## Step 1: Fork the repository +To start, [Fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) the repository. A fork is a copy of the source code that you are free to edit, and later merge into the actual site! To do that: +1. Navigate to https://github.com/thatrobotdev/theorybear +2. Click the Fork button. +3. Click "Create fork" -This guide does not assume any prior software development experience. +## Step 2: Create a GitHub codespace for the site -## Step 1: Create a development environment +To start edtiting the site, you will be creating a **remote development environment** This is a computer running on GitHub's servers that downloads the source code of the site and allows you to edit a version of the website in your web browser! -### How the site works -This site is made with [React](https://react.dev/), a [JavaScript library](https://en.wikipedia.org/wiki/JavaScript_library) that helps in building user interfaces for websites or web applications. - -You don't need to know how React works for this tutorial, but the more you know the more of the site's code that you will understand! - -If you want to dig deeper into how this site works, the following are free tutorials that will take you from zero-knowledge to a pro! - -* If you are unfamiliar with web dvelopment (HTML, CSS), check out [freeCodeCamp's Responsive Web Design Certification](https://www.freecodecamp.org/learn/2022/responsive-web-design/). -* If you are unfamiliar with JavaScript, check out [freeCodeCamp's JavaScript Algorithms and Data Structures Certification](https://www.freecodecamp.org/learn/javascript-algorithms-and-data-structures/). -* If you are familiar with JavaScript, check out the [React Quick Start tutorial](https://react.dev/learn) or [freeCodeCamp's Front End Development Libraries Certification](https://www.freecodecamp.org/learn/front-end-development-libraries/). - -### How we use React - -In conjunction with React, we use a site generator called [Docusarus](https://docusaurus.io/). This is a program that takes input like React-specific files ([.jsx](https://react.dev/learn#writing-markup-with-jsx), [.tsx](https://react.dev/learn/typescript), [.mdx](https://mdxjs.com/)), regular web development files (.html, .css, .js), and text files ([.md](https://www.markdownguide.org/)), to turn into efficient website code! - - -### Finding the site's source code - -This site is [open-source](https://en.wikipedia.org/wiki/Open_source), which means that all of the code that makes it function is published for anyone to view. - -We publish our site's code to GitHub, a code repository that hosts the source code of countless open source projects, at https://github.com/thatrobotdev/theorybear. - -Here is a brief explanation of the structure of the site: - -* blog/ – The folder that holds everything that goes on [theorybear's blog](/blog). -* docs/ – The folder that holds all of the music theory content (including this page)! -* src/ – The folder that holds site code (React components, CSS, complicated pages like the homepage) -* static/ – The folder that holds site images and other assets -* docusaurus.config.js – Main configuration file for the site -* sidebars.js – File that holds information on how the site's sidebar menu should organize links - -Try finding where a specific part of the site is implemented in the code, and see how it is implemented! - -### Creating an editable version of the site - -Now that you have taken a look at the site's structure, it's time to create an "editable" version of the site, or a development environment. - -This will allow you to edit the source code of the site and see a preview of how the site would change with your edit! - -You can either create a local or remote development environment, with different pros/cons of each: - -**Local development environment** -Most common type of development environment, runs on your computer. You are required to download all of the tools that make a website work. Great for working without internet, working with your preferred text editor/development tools. - -**Remote development environment** -Gaining in popularity, runs on someone else's computer. This computer can be standardized so the tools you need can be automatically downloaded. If you mess the development environment up, it's easy to reset and undo changes. - -For this tutorial, we will be using GitHub Codespaces, a remote development environment that allows you to edit code in your web browser using a modified version of the [Visual Studio Code editor](https://code.visualstudio.com/). - -1. Go to the site's source code at https://github.com/thatrobotdev/theorybear +1. Navigate to your fork (usually, https://github.com/[username]/theorybear) 2. Click the green "Code" button, and navigate to the "Codespaces" tab. 3. Sign in/Create a new GitHub account. 4. Click "Create codespace" You should now be able to see a copy of the website in your web browser that you can navigate through in the explore window. Clicking on a file in the left bar will allow you to edit it. -5. In the bottom window, in the terminal, type in the following command and hit ENTER: +## Step 3: Install the site's dependencies and start a development server + +Now is the time to install the packages like [docusarus](https://docusaurus.io/) and [React](https://react.dev/) that allow the site to run! -`npm run start` +1. In the bottom window, in the terminal, type in the following command and hit ENTER: + +`npm install` This command uses the [package manager](https://en.wikipedia.org/wiki/Package_manager) [npm](https://www.npmjs.com/) to download all of the tools that the site needs to build the website from the source code. -6. (window opens) +2. Run `npm run start` to start a development server. You will see a pop-up asking to open a new window. Accept this, and you will see a live-updating version of the site that changes when you change the source code in the GitHub codespaces window! + +### Step 4: Add the splash message -7. Now it's time to add the splash message! In the left window file explorer, navigate to `src/components/Splash/index.tsx`. Find the code that looks like this: +Now it's time to add the splash message! In the left window file explorer, navigate to `src/components/Splash/index.tsx`. Find the code that looks like this: ```js let splashMessages = [ @@ -98,4 +56,41 @@ let splashMessages = [ This is the code that the website randomizes to display a splash message. -The first string in the JavaScript array is the message, and the second string is the attribution. \ No newline at end of file +The first string in the JavaScript array is the message, and the second string is the attribution. Add an element to the array with your unique splash message, and add your first name to the second string in the array. + +```js +let splashMessages = [ + ["You've got this!", "JP"], + ["Need more cowbell!", "JP"], + ["Beary fun music theory ;)", "JP"], + ["Every Good Bear Does Fine", "JP"], + ["FACE!!!!!", "JP"], + ["Arctic Cubs Explore Glaciers :)", "JP"], + ["Open source!!", "JP"] +]; +``` + +### Step 5: Create a pull request to add your changes to the site + +Now that you have edited your local version of the site, it's time to create a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) to add your change to the site! + +1. In VSCode, navigate to the [Source Code tab](https://code.visualstudio.com/docs/sourcecontrol/overview) on the left panel. +2. Enter a message in the message box that describes your changes, like "Added splash message". +3. On the green "Confirm" button, click the arrow on the side to open more actions, clicking "Confirm and Create Pull Request". If you are asked to stage all your changes and commit them directly, hit "Yes". +4. On the pull request screen, create a title for the pull request that describes all of your changes, and add a description if needed. +5. Click "Create" + +### Step 6: 🎉 Wait for Pull Request approval, and celebrate + +If you navigate to https://github.com/thatrobotdev/theorybear/pulls, you should see your pull request in the list on the main repository! This will be reviewed by project maintainers, and then if accepted, merged into the main site! + +Thank you very much for your contribution! + +### Further resources + +If you want to learn more about open-source development, we recommend these resources to get started! + +- [Git and GitHub learning resources](https://docs.github.com/en/get-started/quickstart/git-and-github-learning-resources) +- [freeCodeCamp: Web Design, JavaScript, React, and more!](https://www.freecodecamp.org/) +- [React](https://react.dev/learn) +- [Docusaurus](https://docusaurus.io/docs) \ No newline at end of file