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.
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 has great docs. Rather than recreating them, I'll just link to the most useful ones for editing this site.
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! 🍀
(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...
Developing the website locally requires a few things:
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! :)
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.
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
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.
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.
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
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 :)
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