Getting set up

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

• Node: 8+ but not greater than 14.x (versions above are not supported at this time)
• Yarn: 1.15+

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.

Note: If you get errors installing the dependencies, then check your Node version. Node version greater than 14.x is not supported. Downgrade your Node version to at most v14.18.1.

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.

Preview Deploy a Pull Request

Note: This is only available to authors with push access to this repository and so will not work on pull requests from external (fork) branches.

If you do not have a local development environment or simply wish to easily share a live preview of your changes, it's possible to do so using preview deployments that the continuous integration (CI) environment provides.

Once you have a pull request open, push a commit that contains the text NFDEPLOY in the commit message. We recommend pushing a special, singular commit for this purpose that contains no changes using the git commit --allow-empty command (for example: git commit --allow-empty -m 'NFDEPLOY'). The CI build for this commit will perform a Netlify deployment after the tests have run and then return a unique deployment URL at the end of the logs. Look for a logs section named netlify deploy, expand it, and find the "Website Draft URL:" ending in .netlify.app/. Open this link and share as needed.

If you make subsequent changes, you will need to trigger another preview deployment by pushing a new commit with NFDEPLOY in the commit message (i.e. the deployed site is not "live" updated with the pull request contents).

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.