The Okta developer site serves Okta's API documentation and guides, including:
- API references
- SDK references and sample code
- Authentication quickstarts
- Developer Blog (not published from this repo, see https://github.com/okta/okta.github.io)
If you have questions or need help with Okta's APIs or SDKs, visit the Developer Forum. You can also email developers@okta.com to create a support ticket.
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.
Before getting started, open a terminal window and make sure these commands work:
node --version
yarn --version-
Fork this repository
-
Clone (use the Clone or download button above)
-
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/documentation/ 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/documentation.
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.
Documentation pages are stored as Markdown files in the /packages/@okta/vuepress-site directory.
As an example, lets say you want to edit the Users API page. The public path of this page is /docs/api/resources/users/.
To edit this page, you would navigate to /packages/@okta/vuepress-site/docs/api/resources/users/index.md and edit that Markdown file.
An index.md file in a directory like users will be served as /users/ when the site is live. If you name the file anything other than index.md, you will need to include .html in the URL when you view the page in your browser.
All images and other assets will live in the folder /packages/@okta/vuepress-site/.vuepress/public and should be referenced as such.
There are a few different components that can be used inside the markdown files to render some design specific html
The <ApiOperation> tag is used to render badges representing different API operations (GET, POST, DELETE) in the API reference.
In the Markdown, you can add
<ApiOperation method="delete" url="/api/v1/apps" />and this would render as:
The <ApiLifecycle> tag allows you to mark items as beta, Early Access, or deprecated.
In the Markdown, you can add
<ApiLifecycle access="beta" />and this would render as:
If you need to include a list of links for a category group which was defined in the frontmatter, you can use the CategoryLinks component.
As long as you have the category defined in your markdowns frontmatter such as:
---
category: myCategory
---
You can then use the <CategoryLinks> tag:
<CategoryLinks category="myCategory" />A few options are provided for you to allow for some customization:
| Property | Description |
|---|---|
| category | The category you want to display for the links. This is based on your markdown frontmatter |
| linkPrefix | [ADVANCED] This property allows you to include links based on the path, instead of a category |
| sort | Allows you to sort based on the defined property |
| showExcerpt | This property defaults to true and will display the frontmatter excerpt |
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.
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.
The theme and plugins are in separate packages from content. All of the theme files live in /packages/@okta/vuepress-theme-default – see that package's readme for more info.