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.
If you have never done pull requests, or worked with forks, read the Github Docs Page about it, to get you started quickly.
Go to the polkadot.study github repository and click the fork button at the top right.
Make settings adjustments if you want and click "Create Fork".
Clone the forked repository to your machine in order to make changes. You can copy the forked repository address, by clicking the blue
Codebutton 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.
After you have forked and cloned the repository to your machine, to run it you
need to install the dependencies with
# go to the directory you cloned into, e.g.
# install dependencies
If you do not have
yarn on your machine, please follow
this guide. We currently use node
Running the docusaurus development server
Before you start the dev server, you need to update git submodules.
git submodule init
git submodule update --remote
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
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.
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 firstname.lastname@example.org:PolkadotStudy/polkadot.study.git
git fetch upstream
git merge upstream/staging