Setup the Development Environment

Before you learn about the recommended style and structure of your polkadot.study tutorial, we will walk you through the process of creating a local environment that you can later use for submitting your tutorial to our website and for local preview.

Forking the Repository

Polkadot.study uses the fork-and-pull-model. Meaning, that anyone can submit pull requests from their own forks of the repository. The project maintainer, can then (after discussing, reviewing and revising) merge your changes to the main repository and make it part of the website.

info

If you have never done pull requests, or worked with forks, read the Github Docs Page about it, to get you started quickly.

1. Go to the polkadot.study github repository and click the fork button at the top right.

2. Make settings adjustments if you want and click "Create Fork".

3. Clone the forked repository to your machine in order to make changes. You can copy the forked repository address, by clicking the blue Code button and then

git clone <your forked repo url>

You now have everything to start writing / developing locally, as well as a setup for later making a Pull Request to our repository. You might have noticed that the default branch is set to staging. You can always see a preview of staging at staging.polkadot.study.

info

If you get lost, or if anything is unclear, please contact authors@polkadot.study or submit a github issue.

Running Locally

After you have forked and cloned the repository to your machine, to run it you need to install the dependencies with yarn.

# go to the directory you cloned into, e.g.
cd polkadot.study
# install dependencies
yarn

info

If you do not have node.js and yarn on your machine, please follow this guide. We currently use node v18.

Running the docusaurus development server

Before you start the dev server, you need to update git submodules.

git submodule init
git submodule update --remote

::: info

Polkadot.study integrates markdown files from other repositories and uses submodules in order to make updates easier.

:::

Now, to start the docusaurus dev server, do

yarn start

Then, navigate to localhost:3000. The dev server supports hot module loading and will automatically update when you change and save your tutorial files.

You cannot see any changes in the tutorial tab yet, just the ones others published, you will change that in the next step and wire your tutorial in.

Updating your fork

Your fork might get outdated as others make changes to the staging branch. To keep your branch up to date sync your fork from time to time, especially before submitting a PR.

warning

If there are merge conflicts, do not click the "Discard Changes" button but rather use a command line tool or any git UI to resolve those conflicts.

If you are using the command line, you can do the following to merge and resolve the merge conflicts locally.

git remote add upstream git@github.com:PolkadotStudy/polkadot.study.git
git fetch upstream
git merge upstream/staging