Creating a Guide

Our guides center around specific use cases, and describe the steps that you would take in order to fulfill those use cases. They are broken down by steps and usually can be displayed with embedded information that shows further information about performing that step in a particular language or framework.

Adding and editing pages

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/reference/api/users/. To edit this page, you would navigate to /packages/@okta/vuepress-site/docs/reference/api/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.

For a link to a new Concepts or Reference page to be included in the site's left side navigation bar, you need to edit the file that controls that navigation bar. See Left Side Navigation.

More information about writing content for VuePress can be found in our VuePress Authoring Guidelines. There you will also find our Style Guide.

Directory Structure

Every guide is based in a subdirectory under packages/@okta/vuepress-site/docs/guides/. The subdirectory name is used in the url for the guide, so follow best practices for URLs (human-readable, lowercase, no spaces, no special characters other than '-'). For example: packages/@okta/vuepress-site/docs/guides/name-of-guide/name-of-framework/name-of-section

The docs/guides/index.md file contains the overall meta-data for all the guides in the front matter. This file contains the ordered list of guides offered and the ordered list of "featured" guides for the main Guides page. (TODO: Move content from GuidesOverview to this index.md file) If a guide is not listed in this file, it IS on the site but is NOT linked to.

Each guide directory will have a number of section subdirectories. These are used in the urls for each section of the guide, so follow best practices for URLs in naming these directories. Each guide directory has an index.md file that holds meta-data for the guide, notably the ordered list of section directories. Any section directory not listed can be accessed on the site but will not be linked to. Each section directory has an index.md file that holds the Markdown content for that section. For example: docs/guides/name-of-guide/name-of-section/index.md

If a guide section has framework-specific content, you can use <StackSelector snippet="SNIPPET-NAME"/> where SNIPPET-NAME is a section-specific indicator of your choice. This does NOT appear in a url, but please follow common filename conventions.

Content for the StackSelector snippets are found in docs/guides/NAME-OF-GUIDE/NAME-OF-SECTION/NAME-OF-FRAMEWORK/SNIPPET-NAME.md files.

Constructing a new guide

Steps

1. Create the guide directory
2. Create the guide index.md
3. Create a subdirectory for every section
4. Put your Markdown content into the index.md file for each section subdirectory
5. For any snippets you declare, create the NAME-OF-FRAMEWORK/NAME-OF-SNIPPET.md files in the section subdirectory
6. Make sure the index.md file for the section includes the title of the section
7. Make sure the index.md file for the guide includes the title for the guide and the list of all section subdirectories (in order)
8. Make sure the main guides index.md file lists your guide in the desired position in the order

Using the "Stack Selector"

Many guide sections will have one or more areas of framework-specific content. This can be code, instructions, or a mix of the two. When a guide section has need of such content, simply use <StackSelector snippet="SNIPPET-NAME"/> in your section index.md content where you want some framework-specific content to appear. Then create the relevant content in NAME-OF-FRAMEWORK/SNIPPET-NAME.md files for every relevant framework.

Writing framework-specific content

Each guide should have the same list of frameworks for all StackSelectors in all sections of that guide; however, each individual guide can have a distinct list of frameworks that does not have to be the same as other guides. For example, a mobile guide might have ios, android, and reactnative frameworks, while a front-end web guide might have react, angular, and vue options.

The framework names in the directories should be entered using lower case and without special characters. The list of frameworks supported with icons and human-readable names are:

• android
• ios
• reactnative
• xamarin
• angular
• preact
• react
• vue
• go
• node
• java
• php
• python
• spring
• dotnet
• dotnetcore
• aspnet
• aspnetcore

Linking between sections and guides

Always have a trailing slash at the end of your guides link. (Example: /guides/NAME-OF-GUIDE/-/NAME-OF-SECTION/)

Links and Guides have some complications because of the "magic" nature of the selected framework. For links within or between guides, follow these examples:

• Linking to a different section of the same guide:
  • Use <GuideLink> and always go "up" one directory
  • <GuideLink link="../NAME-OF-SECTION">Text to show</GuideLink>
  • This will maintain the selected framework
• Linking to a different guide:
  • Normal markdown links work
  • [Text to Show](/guides/NAME-OF-GUIDE/)
  • This will select the first framework and first section and update the url to match.
• Linking to a specific section of a different guide:
  • Normal markdown links work
  • use - in place of a framework if you aren't linking to a specific framework
  • [Text to Show](/guides/NAME-OF-GUIDE/-/NAME-OF-SECTION/)
  • This will select the first framework and update the url to match
• Linking to another section as part of the guide navigation
  • <NextSectionLink/> - Provides a "button" link to the next section
  • <NextSectionLink>Some Example Text</NextSectionLink> - Provides the "button" with different text
  • <NextSectionLink name="next-steps"/> - Provides the "button" to link to the named section of the guide (doesn't have to be the "next" section)

Theme and Plugin Contribution

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.