The Okta developer site serves Okta's API documentation and guides, including:
- API references
- SDK references and sample code
- Authentication quickstarts
- Guides
- Developer Blog (not published from this repo, see okta/okta.github.io)
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.
If you want to run yarn build, you must have a node version of 13+
Before getting started, open a terminal window and make sure these commands work:
node --version
yarn --version- Depending on your permissions, clone or fork the repo (if you fork the repo, be sure to Allow edits from maintainers).
- Install the dependencies with
yarn:
cd okta-developer-docs
yarn installThis will install everything you need to build the documentation on your machine.
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. 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. Once the server is running on your machine, any changes you make to Markdown content will appear automatically in your browser within a few seconds. Note that changes to page frontmatter or site configuration require you to stop and start the preview server.
If you are on a Windows machine you may experience the following issues.
Because Windows handles line endings differently than *nix operating systems, you may see the following error after running yarn dev:
yarn run v1.22.4
$ yarn workspace @okta/vuepress-site dev
$ yarn conductor:validate && vuepress dev .
$ node .vuepress/scripts/yml-parse-check.js
conductor.yml parse successful
conductor.yml exports correct values
Error: Error: conductor.yml must end in a new (but not blank) line
at Object.<anonymous> (C:\src\repos\okta-developer-docs\packages\@okta\vuepress-site\.vuepress\scripts\yml-parse-ch
eck.js:68:11)
at Module._compile (internal/modules/cjs/loader.js:1133:30)
at Object.Module._extensions..js (internal/modules/cjs/loader.js:1153:10)
at Module.load (internal/modules/cjs/loader.js:977:32)
at Function.Module._load (internal/modules/cjs/loader.js:877:14)
at Function.executeUserEntryPoint [as runMain] (internal/modules/run_main.js:74:12)
at internal/main/run_main_module.js:18:47
error Command failed with exit code 1.
...
To resolve this issue run the following command from a bash prompt (included with git for windows installation):
dos2unix ./packages/\@okta/vuepress-site/conductor.ymlDue to limitations of the Windows file system you may see the following error after running yarn dev:
yarn run v1.22.4
$ yarn workspace @okta/vuepress-site dev
$ yarn conductor:validate && vuepress dev .
$ node .vuepress/scripts/yml-parse-check.js
conductor.yml parse successful
conductor.yml exports correct values
conductor.yml end-of-file check successful
wait Extracting site metadata...
Error: Cannot resolve theme: @okta/vuepress-theme-prose.
at resolveTheme (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\node\loadTheme.js:111:13)
at loadTheme (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\node\loadTheme.js:36:17)
at App.process (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\node\App.js:100:21)
at processTicksAndRejections (internal/process/task_queues.js:97:5)
at async dev (C:\src\repos\okta-developer-docs\node_modules\@vuepress\core\lib\index.js:14:3)
error Command failed with exit code 1.
...
To resolve this issue run the following commands from a bash prompt (included with git for windows installation):
cd ./packages/\@okta/vuepress-theme-prose/
yarn link
cd ../../../
yarn link "@okta/vuepress-theme-prose"- Developer docs: https://developer.okta.com
- Developer forum: https://devforum.okta.com
- VuePress software: https://vuepress.vuejs.org
See our updated wiki for full details on contributing to the developer documentation repo: