Skip to main content

Setting up the environment

This is a quick guide to get the VS Code/Docusaurus environment up and running on a local machine. It shows how to install the necessary tools and how to copy the whole project from the GitHub repo.

Things to install:​

  • Visual Studio Code
  • "npm" command
  • "git" command

How to install "npm"​

npm or "Node Package Manager" is a tool for installing and managing software packages. In our case, it's used to install dependencies for the Docusaurus platform, including Docusaurus itself. It can also be used to run a local test server to review changes before committing them to GitHub.

npm is built on the Node.js platform, so that has to be installed as well if it isn't already. Luckily, they can both be installed at the same time with one package:

Download and run the Windows installer from: https://nodejs.org/en/download/prebuilt-installer

Nothing needs to be changed from the suggested install settings. If needed, a more detailed guide can be found at: https://phoenixnap.com/kb/install-node-js-npm-on-windows

To verify that the installation went okay, open up a command prompt and write: npm -v

A version number should be displayed.

How to install "git"​

git is a command that helps interact with GitHub from a local machine. It's more powerful than the UI in VS Code, but a bit trickier to use since everything is done from the command line. Right now, we'll only use it to clone the GitHub repo.

Now that we have npm installed, all we need to do is open up a command prompt and type: npm install -g git

After it's finished, check that it's ready to use with: git -v

The version number should show up.

Cloning Docs-Products GitHub repo​

  • Open up a command prompt (as Administrator if available)
  • Change the folder to a suitable one for projects. The project folder itself will be created automatically under that.
  • Clone the GitHub repo: git clone https://github.com/signupsoftware/Docs-Products

The source code should now be downloaded, but since it's just the code and nothing else, we need to install all dependencies.

  • CD to the Docs-Products folder and type: npm install

It could take a couple of minutes (ignore warning messages), but after that, everything is ready to use. Start VS Code by typing cd Docs-Products in the command prompt and then: code .

VS Code can, of course, be started normally like any other Windows application. To get to the Docusaurus project, just use File -> Open folder and browse to the folder we just cloned. VS Code doesn't use a project file; it just needs to be pointed to the root folder of the project.

Previewing pages​

Docusaurus is built on the React platform and can be used to view changes in text/pages in real-time. You make a change in a page, and it will show up automatically in a browser when saved.

To facilitate this, a web server has to run locally in the background. That part is handled by VS Code; we only need to give the command to start it:

  • In VS Code, go to the top menu "Terminal", under that, pick "New Terminal".
  • A panel should open up at the bottom in VS Code. In that panel, type: npm run start

It takes a couple of minutes to get going, but a web page should open up automatically in a browser. It will display the page exactly as it will look when published to the web.