@slashid/docusaurus-theme-slashid

Docusaurus SlashID Theme

SlashID theme to add authentication to Docusaurus.

---

Overview

The @slashid/docusaurus-theme-slashid package extends Docusaurus to add authentication to docusaurus. The theme can be combined with docusaurus openapi docs to preload API keys and API parameters directly through SlashID attributes.

Key Features:

• Compatible: Supports Magic Links, Passkeys, OTP via sms and SSO.
• Personalization: Allows to load per-user configuration data into docusaurus.

Installation

Theme:

# npm
npm install @slashid/slashid @slashid/react @slashid/docusaurus-theme-slashid
# yarn
yarn add @slashid/slashid @slashid/react @slashid/docusaurus-theme-slashid

Configuring docusaurus.config.js

Add the following to docusaurus.config.js to start using the theme:

// docusaurus.config.js

{
  ...

   themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
     ({
      ...
      slashID: {
        orgID: "your slash id org id",
        oidcClientID: "optional OIDC client ID",
        oidcProvider: "optional OIDC provider name",
        forceLogin: "boolean flag to determine if login is required",
        baseURL: "optional base API URL for the SDK, defaults to the production environment",
        sdkURL: "optional base SDK page URL for the SDK, defaults to the production environment",
        privatePaths: [
          {
            path: "a glob or a regex specifiying the path to protect",
            groups: ["optional list of groups that can access the path"],
          }
        ],
      },

    themes: ["@slashid/docusaurus-theme-slashid"],
  }
}

Also please remember to include the login form styles:

// under presets

{
    theme: {
        customCss: [
            require.resolve("./src/css/custom.scss"), // existing custom css
            require.resolve("@slashid/react/style.css"), // add this line
        ],
    }
}

Theme Configuration Options

The docusaurus-theme-slashid theme can be configured with the following options:

Name	Type	Default	Description
slashID.orgID	string	null	The SlashID organization ID.
slashID.oidcClientID	string	null	OIDC client ID.
slashID.oidcProvider	string	null	OIDC provider name.
slashID.forceLogin	boolean	false	Make login required.
slashID.baseURL	boolean	false	Base API URL for the SDK, defaults to the production environment.
slashID.sdkURL	boolean	false	Base SDK page URL for the SDK, defaults to the production environment.
slashID.privatePaths	PrivatePath[]	undefined	Optional set of private paths.

Interface: PrivatePath

A private path is a path that requires authentication to access. The slashID.privatePaths option is an array of PrivatePath objects.

interface PrivatePath {
  path: string; // a glob or a regex specifiying the path to protect
  groups?: string[]; // optional list of groups that can access the path
}

Page level configuration

The theme can be configured at the page level using front matter to pass sidebar_custom_props.

sidebar_custom_props:
  slashid:
    auth: true
    groups:
      - member

The above configuration will require the user to be authenticated and belong to the member group to view the page. groups property is optional and if not specified, the user only needs to be authenticated to view the page.

Support

Please read SUPPORT.md for details on how to get support for this project.

Changelog

0.3.3 (Feb 5, 2024)

High level enhancements

• upgraded @slashid/react to v1.18.0
• upgraded @slashid/slashid to v3.18.0

Other enhancements and bug fixes

• added ServerThemeProvider to the theme Root to fix the issue with CSS variables not applied correctly