Skip to content

VuePress Authoring Guidelines

Jump to bottom
Jakub Vul edited this page Apr 24, 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.

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

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" />

Images

Include images in your page using this:

![Image Name](/path/to/image "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

Clone this wiki locally