-
Notifications
You must be signed in to change notification settings - Fork 593
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.
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- 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).
- Install the dependencies with
yarn:
cd okta-developer-docs
yarn installThis installs everything you need to build the documentation on your machine.
Note: If you get errors installing the dependencies, then check your Node version. Downgrade your Node version if required. Be sure to check the error message and the version dependency based on your version of Yarn. There are several Yarn/Node pairings that work, some of which include: Yarn 1.22.19 and node 14.18.1; Yarn 1.22.18 and node 14.18.1; Yarn 1.22.17 and node 14.13.1; and Yarn 1.22.22 and node 16.18.1.
With the above steps completed, you can start a preview server by running this command inside the cloned directory:
yarn devThis starts a preview server on your machine, and watches all files for changes. Wait until the server is running and then open http://localhost:8080/ to view the site. Look for the line:
success [19:05:24] Build 7c47ac finished in 1368 ms! ( http://localhost:8080/ )Note: if the root page is blank, stop the server and run
yarn installbefore runningyarn dev. You should only have to re-runyarn installwhen 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.
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 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-onlyinstead. This skips starting up the preview server.
If your test run fails unexpectedly, try executing yarn stop and running the tests again.
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.