Contribution Guide

This website is built with Docusaurus! 🦕

This means that unless you want to change the architecture of the site (adding/removing sections, reorganizing, etc) you should be able to just create and edit Markdown docs.

Examples 👀

If you want an example of what Docusaurus can do, look no further than the official Docusaurus website. Another great example is hack.aragon.org. Since Docusaurus is based on React, you can extend and customize it as little or as much as you'd like.

Docusaurus Docs 📚

Docusaurus has great docs. Rather than recreating them, I'll just link to the most useful ones for editing this site.

• Markdown Guide - how to use Markdown in Docusaurus
• Navigation and Sidebars - this explains how to link a new Markdown document to the rest of the website.
• Publishing Your Site - this explains how to publish the work you do locally to the actual website.

Hacking On Docusaurus 💻

TL;DR: to hack

Pull the repo to your local machine. Go into the website directory

• yarn (to init stuff)
• yarn start (to build and serve locally)

~ Everything that is a String can be edited via Markdown. The hot-reload server will show these changes if you refresh the local build in the browser.

If you change anything using Javascript, you're probably going to need to disengage yarn then run yarn start again to see changes

Good luck! 🍀

TL;DR: to publish

(assuming you have push access to the website repo, otherwise keep the local configuration in siteConfig.js and just submit a PR)

Uncomment stuff in siteConfig.js to configure for publishing to website (not gh-pages)

Then navigate to the website directory

Then run the script below

GIT_USER=your-username CURRENT_BRANCH=master yarn run publish-gh-pages

When you're done publishing, go to the github repo (https://github.com/1Hive/website/), click on settings, and make sure that under GitHub Pages 1hive.org is set as the custom domain and it says: "Your site is published at https://1hive.org/"

Here's the long form of what that all looks like...

Prerequisites

Developing the website locally requires a few things:

• Git (sudo apt-get install git on linux)
• Node
• Yarn

If these are not enough, you can check out my Linux Dev Env quickstart guide to see what I'm running locally. If you discover a required dependency that is not in the list above, please open an issue to let me know! :)

Pulling the master branch

You'll then go to whatever directory you want to work on the project in and run

• git clone https://github.com/1Hive/mvp.git

This will pull all the data to your local environment.

Configuring siteConfig.js

Run cd mvp/website/ to go to the directory that serves the Docusaurus website

Open siteConfig.js and check that the correct stuff is commented/uncommented for local development vs publishing

• https://github.com/1Hive/mvp/blob/master/website/siteConfig.js#L27

Building Locally

Make sure that you're still in the website directory (~/mvp/website/)

• yarn (to init stuff)
• yarn start (to serve stuff locally)

If yarn start is successful you will see the following output

LiveReload server started on port 35729
Docusaurus server started on port 3000

To see the website open localhost:3000 in your browser.

If you do not see the site, please go back to the beginning of this doc and try again following all the steps. If that still does not work please open an issue or comment and I'll help however I can.

• note: I work on a remote VM that I ssh into so I won't know much about developing this on a laptop like Macbook.
• another note: I don't like npm because it's slow and lame, so I'm using Yarn. Happy to help troubleshoot Yarn, but not npm

If everything is working, you can expect changes to the UI or Markdown to hot reload with a refresh of the page. Changes to Javascript related things will require you to disengage yarn start using ctrl C, then re-engage by running yarn start again. This causes Yarn to reload the whole thing ensuring that your JS changes show up.

Publishing

To publish you'll need to navigate to the website directory (~mvp/website/) and change the parameters in siteConfig.js to comment out local development and enable publishing.

• https://github.com/1Hive/website/blob/master/website/siteConfig.js#L13

• note: if you have 2FA enabled on your GitHub profile (and you would be wise to do so), you'll need to provide your GitHub API access token rather than your account password. You can learn about how to do that here

• test that it's working by creating a small change to the README.md, going to the root directory of the project (~/mvp/) and pushing it to the repo

  git add . git commit -m "testing git login" git push

Once you've got that figured out... navigate to the website directory (~/mvp/website/) and run the following command to publish:

GIT_USER=your-username CURRENT_BRANCH=master yarn run publish-gh-pages

After about a minute (sometimes 5min) it should populate to the actual website URL: 1hive.org

❗ You're not done!

Once you've published, go to the github repo (https://github.com/1Hive/website/), click on settings, and make sure that under GitHub Pages 1hive.org is set as the custom domain and it says: "Your site is published at https://1hive.org/"

Also, before submitting any more PRs or pushes make sure that siteConfig.js is configured for local development so that it's ready for anyone to pulls the repo and work on it locally :)

Hope that helps! :)

Notes 📝

If you want the fun minimap to show up on the left side of the screen you need to use ## before each title.

Remember, that for the website to actually display stuff in docs or blog, you need to link them

• Navigation and Sidebars - this explains how to link a new Markdown document to the rest of the website.