Skip to content

VuePress Authoring Guidelines

Jump to bottom
Jakub Vul edited this page Sep 19, 2019 · 8 revisions

File Naming

File names should be short, all lowercase, with words separated by hyphens.

Front Matter

Every page can specify a layout in its front matter. If you do not specify a layout, VuePress will default to the default one, which is simply Layout. So for a standard API reference page, you would use this front matter:

---
title: Your title
excerpt: A short description
---

Our layouts are stored in the packages/@okta/vuepress-theme-default/layouts directory.

Headings

We use the atx style for our headers.

# This is an H1

## This is an H2

### This is an H3

The content under the front matter should not have any h1s - this will be set by the title property

All h2s in the content will be rendered as a link in the table of contents that renders on the right of the page.

Note: Anchor tags for headings will only render alphanumeric characters, along with - (dash) and _ (underscore). All other characters will be removed.

Okta URLs

Any generic Okta URL should be added with the following format:

https://{yourOktaDomain}/further/path/goes/here

If the reader has an active session, the {yourOktaDomain} placeholder text will be replaced by their actual Okta Org URL.

API CRUD Tags

CRUD operation graphics are rendered using the following code:

<ApiOperation method="CRUDOperationHere" url="/api/v1/path/goes/here" />

Available operations are:

  • post
  • get
  • put
  • delete

For example, this Markdown:

<ApiOperation method="delete" url="/api/v1/apps" />

would render as:

Lifecycle Tags

We have special markdown tags and a custom plugin which enables you to mark content as Early Access and Deprecated in the API docs.

Note: Apply the tag to the top of the file after the title if the whole API is affected by the status. Otherwise, apply it to the most appropriate section, or next to the property name in a table.

  • Early Access content: <ApiLifecycle access="ea" />
  • Deprecated content: <ApiLifecycle access="deprecated" />

For example, if you add

<ApiLifecycle access="beta" />

this would render as:

Images

Include images in your page using this:

![Image Name](/img/filename.png "Your Alt Text")

The image files (we prefer .png) should be added to the packages/@okta/vuepress-site/.vuepress/public/img directory. Subdirectories are supported.

Left Side Navigation

If you'd like to add something to the navigation bar, edit the following file:

packages/@okta/vuepress-site/.vuepress/nav/main.js

Category Links

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
Clone this wiki locally