frc2508.org

The official Armada Robotics 2508 website. Created using Ruby, Middleman, and ERB.

Bugs/Enhancements

New features, suggestions, and existing bugs should be tracked on the Github issues page.

Setup

1. Install the latest version of Ruby (use https://rubyinstaller.org for Windows).
2. Clone this repository with git clone https://github.com/Armada2508/frc2508.org.git.
3. Navigate to the root directory of this repository in a command prompt.
4. Type bundle install (you may need gem install bundle first).
5. If you're using VSCode I recommend installing this extension for improved syntax highlighting.

Code Formatting

All of the website code is formatted using two different tools, HTML Beautifier and Prettier.

HTML Beautifier

HTML Beautifier is a Ruby gem that is used to format the erb files. It will be installed when you run bundle install from the setup. It can be run using the command

htmlbeautifier .\source\**\**.erb

There is a corresponding VSCode extension to do the formatting for you.

Prettier

Prettier is a javascript formatting tool. It formats files such as css, js, and yml.
It can be installed locally through NPM but it's easier to install the VSCode extension for it.

VSCode Settings

If you have installed the two formatting extensions and want your code to be formatted on save you can add this to your VSCode user settings.json

"[erb][css][javascript][yaml]": {
    "editor.formatOnSave": true
},
"[erb]": {
    "editor.defaultFormatter": "aliariff.vscode-erb-beautify"
},
"[css][javascript][yaml]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
},

Running the Website Locally

1. Run bundle exec middleman server.
2. In your favorite browser go to https://localhost:4567.

Deploying Changes

1. Create a new branch with git switch -c branchname.
2. Commit your changes with git commit -m "commit message".
3. Push your changes to your new branch with git push.
4. Open a pull request, merge your branch into master, and wait for gh actions to deploy.

Pull Request Previews

Our website supports previewing the changes a PR makes through the use of this github action. Cool, right?
This allows others to see the changes you've made to the website without them downloading the repo and tools needed to run it locally.
Once a pull request is created the website will be built and then deployed under a subdirectory. A comment will appear on the pull request with a link to the preview version of the website. It will be updated every time you push a new commit, but keep in mind it takes time (~2-3 minutes) for Github Pages to deploy.

The <base> element and you

In order for all of the links to other pages and assets to reference the correct items in a preview we use the <base> element. This takes every relative link (href/src) and prepends it with a base url. The <base> element's href is automatically configured by our github action. When developing on the website and you reference an internal resource, you should ensure it's a relative link so it works with our previews.

To make an absolute link relative, all you have to do is drop the leading slash.
For example instead of writing src="/assets/images/img.jpg" you write src="assets/images/img.jpg". You would do something similar with an <a> element's href.

Finally, because we use the <base> element it means every relative link is prepended with a url. This means if you have a link to an ID on the same page (e.g. <a href="#bar">), you need to write the page as well, <a href="foo#bar">.

Further reading, https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base.