Skip to content

Getting set up

Jump to bottom
Brett Ritter edited this page Feb 22, 2021 · 20 revisions

Okta's developer documentation (this repo) is built using the VuePress site generator.

There are currently 2 parts to the site: the content and the theming/plugins.

Requirements

We recommend using one of the package manager options for installation as specified in the installation sites.

Before getting started, open a terminal window and make sure these commands work:

node --version

yarn --version

Local setup

  1. If you have an Okta GitHub account, clone the repo (use the Clone or download button on the main repo page). Otherwise, fork the repo and be sure to Allow edits from maintainers).
  2. Install the dependencies with yarn:
cd okta-developer-docs

yarn install

This installs everything you need to build the documentation on your machine.

Previewing the site

With the above steps completed, you can start a preview server by running this command inside the cloned directory:

yarn dev

This starts a preview server on your machine, and watches all files for changes. Open http://localhost:8080/ to view the site.

Note: if the root page is blank, stop the server and run yarn install before running yarn dev. You should only have to re-run yarn install when you've pulled in changes to the underlying server configuration.

The preview server supports hot reloading: after the server is running on your machine, any changes you make to Markdown content appear automatically in your browser within a few seconds. Note that any changes to the page frontmatter or site configuration require you to stop and start the preview server.

Stop the preview server by pressing CTRL+c.

Running tests

Running the tests before committing should be done and can be accomplished by running yarn test from the terminal. This will run a series of tests to make sure that everything is working as expected and that your changes did not affect anything that was not planned.

Note: If you're already running the preview server locally, you can run yarn test-only instead. This skips starting up the preview server.

If your test run fails unexpectedly, try executing yarn stop and running the tests again.

Does the site need to be built before it can be committed?

There is no need to build the rendered site before committing and submitting a PR. This will all happen on the CI side to test and build the rendered site.

Clone this wiki locally