Skip to content

Getting set up

Jump to bottom
Ian Hakes edited this page Aug 24, 2019 · 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. Fork this repository
  2. Clone (use the Clone or download button on the main repo page)
  3. 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/docs/ to view the documentation.

Note: if you try to visit the root, you will get a 404 page. You must visit a path corresponding to a directory under vuepress-site, like /docs/.

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.

What About Building the Site Before Committing?

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