Greatly improves documentation

.gitignore

@@ -14,6 +14,7 @@ node_modules
 testenv
 testenv*
 testenv.yml
+.watchmanconfig
 
 # Testing
 coverage
@@ -46,6 +47,7 @@ dist
 
 
 # Debug
+*.log
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

docs/.vitepress/config.mts

@@ -1,7 +1,9 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from 'vitepress';
+import { withMermaid } from 'vitepress-mermaid-viewer';
 import authFoundationSidebar from './typedoc-configs/auth-foundation-sidebar.json';
 import oauth2FlowsSiderbar from './typedoc-configs/oauth2-flow-sidebar.json';
 import spaPlatformSidebar from './typedoc-configs/spa-platform-sidebar.json';
+import RNPlatformSidebar from './typedoc-configs/react-native-platform-sidebar.json';
 
 
 import { createRequire } from 'node:module';
@@ -11,107 +13,137 @@ const pkg = require('../../package.json');
 const minorVersion = pkg.version.split('.').slice(0, -1).join('.');
 
 
+// Only applies to `yarn docs:build` (`NODE_ENV=production`) - a `base` path breaks local dev
+// (`yarn docs:dev`), since the dev server itself isn't served from that subpath.
+const base = process.env.NODE_ENV === 'production' ? '/okta-client-javascript/' : undefined;
+
 // https://vitepress.dev/reference/site-config
-export default defineConfig({
-  title: "Okta Client JavaScript",
-  titleTemplate: 'Okta Client JS',
-  description: "",
-  cleanUrls: true,
-  head: [
-    ['link', { rel: 'icon', href: '/favicon.ico' }]
-  ],
-  themeConfig: {
-    // https://vitepress.dev/reference/default-theme-config
-    siteTitle: `Okta Client JS (v${minorVersion}-beta)`,
-    nav: [
-      { text: 'Home', link: '/' },
-      { text: 'Docs', link: '/docs' },
-      { text: 'API', link: '/api' },
-      // { text: 'Blog', link: '/blog' },
-      {
-        text: `v${minorVersion} (beta)`,
-        items: [
-          // TODO: update before public release
-          { text: 'Changelog', link: 'https://github.com/okta/okta-auth-js/blob/master/CHANGELOG.md' }
-        ]
-      }
+export default withMermaid(
+  defineConfig({
+    base,
+    title: "Okta Client JavaScript",
+    titleTemplate: 'Okta Client JS',
+    description: "",
+    cleanUrls: true,
+    ignoreDeadLinks: true,
+    head: [
+      ['link', { rel: 'icon', href: '/favicon.ico' }]
     ],
-
-    sidebar: {
-      '/docs/': [
-        {
-          text: 'Getting Started',
-          link: '/docs/index.md'
-        },
+    themeConfig: {
+      // https://vitepress.dev/reference/default-theme-config
+      siteTitle: `Okta Client JS (v${minorVersion}-beta)`,
+      outline: {
+        level: [2, 3]
+      },
+      nav: [
+        { text: 'Home', link: '/' },
+        { text: 'Docs', link: '/docs' },
+        { text: 'API', link: '/api' },
+        // { text: 'Blog', link: '/blog' },
         {
-          text: 'Project Structure',
-          link: '/docs/structure.md'
-        },
-        {
-          text: 'Installation',
-          link: '/docs/installation.md'
-        },
-        {
-          text: 'Concepts',
+          text: `v${minorVersion} (beta)`,
           items: [
-            {
-              text: 'OAuth2',
-              link: '/docs/concepts/oauth2.md'
-            },
-            {
-              text: 'Sessions',
-              link: '/docs/concepts/sessions.md'
-            },
+            { text: 'Changelog', link: 'https://github.com/okta/okta-client-javascript/blob/master/CHANGELOG.md' }
           ]
-        },
-        {
-          text: 'Guides',
-          link: '/docs/guides/',
-          items: [
-            {
-              text: 'Managing User Credentials',
-              link: '/docs/guides/Credential.md'
-            },
-            {
-              text: 'Consuming Tokens Within an Application',
-              link: '/docs/guides/TokenOrchestrator.md'
-            },
-            {
-              text: 'Making Authenticated Requests',
-              link: '/docs/guides/FetchClient.md'
-            },
-          ]
-        },
-        {
-          text: 'Testing',
-          link: '/docs/testing/',
-          items: [
-
-          ]
-        }
-      ],
-      '/api/': [
-        {
-          text: 'auth-foundation',
-          link: '/api/auth-foundation/',
-          items: authFoundationSidebar
-        },
-        {
-          text: 'oauth2-flows',
-          link: '/api/oauth2-flows/',
-          items: oauth2FlowsSiderbar
-        },
-        {
-          text: 'spa-platform',
-          link: '/api/spa-platform/',
-          items: spaPlatformSidebar
         }
       ],
-    },
 
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
-    ]
-  },
-  ignoreDeadLinks: true
-});
+      sidebar: {
+        '/docs/': [
+          {
+            text: 'Getting Started',
+            link: '/docs/index.md'
+          },
+          {
+            text: 'Project Structure',
+            link: '/docs/structure.md'
+          },
+          {
+            text: 'Installation',
+            link: '/docs/installation.md'
+          },
+          {
+            text: 'Concepts',
+            items: [
+              {
+                text: 'OAuth2',
+                link: '/docs/concepts/oauth2.md'
+              },
+              {
+                text: 'Sessions',
+                link: '/docs/concepts/sessions.md'
+              },
+            ]
+          },
+          {
+            text: 'Guides',
+            items: [
+              {
+                text: 'Managing User Credentials',
+                link: '/docs/guides/Credential.md'
+              },
+              {
+                text: 'Consuming Tokens Within an Application',
+                link: '/docs/guides/TokenOrchestrator.md'
+              },
+              {
+                text: 'Making Authenticated Requests',
+                link: '/docs/guides/FetchClient.md'
+              },
+              // {
+              //   text: 'Testing',
+              //   link: '/docs/testing/',
+              //   items: [
+
+              //   ]
+              // }
+            ]
+          },
+          {
+            text: 'References',
+            items: [
+              {
+                text: 'Authorization Code Flow',
+                link: '/docs/references/authorization_code_flow.md'
+              },
+              {
+                text: 'RP-Initiated (Session) Logout',
+                link: '/docs/references/session_logout_flow.md'
+              },
+            ]
+          },
+        ],
+        '/api/': [
+          {
+            text: 'auth-foundation',
+            link: '/api/auth-foundation/',
+            items: authFoundationSidebar
+          },
+          {
+            text: 'oauth2-flows',
+            link: '/api/oauth2-flows/',
+            items: oauth2FlowsSiderbar
+          },
+          {
+            text: 'spa-platform',
+            link: '/api/spa-platform/',
+            items: spaPlatformSidebar
+          },
+          {
+            text: 'react-native-platform',
+            link: '/api/react-native-platform',
+            items: RNPlatformSidebar
+          }
+        ],
+      },
+
+      socialLinks: [
+        { icon: 'github', link: 'https://github.com/okta/okta-client-javascript' }
+      ]
+    },
+    mermaid: {
+      download: false,
+      downloadPng: false
+    }
+  })
+);