cli/workspaces/documentation-ui at master

🐤 Documentation and Wiki UI 👀

📢 About

Portable documentation/wiki UI for NodeSecure tools like CLI or Preview. This package has been designed with the objective of rendering the same documentation to all developers whatever the tool they use.

📜 Features

Render NodeSecure flags using the package @nodesecure/flags.
Render NodeSecure JS-X-RAY SAST Warnings.

Note

The content is retrieved from the github API (and sometimes it transform raw markdown response to HTML, that's why we use markdown-it as dependency).

💃 Getting Started

This package is available in the Node Package Repository and can be easily installed with npm or yarn.

$ npm i @nodesecure/documentation-ui
# or
$ yarn add @nodesecure/documentation-ui

👀 Usage example

// Import Third-party Dependencies
import * as documentationUI from "@nodesecure/documentation-ui";

document.addEventListener("DOMContentLoaded", async () => {
  const documentRootElement = document.getElementById("whatever-you-want");

  const wiki = documentationUI.render(documentRootElement, {
    prefetch: true,
  });

  console.log(`Available views: ${[...wiki.header.views.keys()].join(",")}`);
  wiki.header.setNewActiveView("warnings");

  // Note: you can also enumerate menus with `wiki.navigation.warnings.menus.keys()`
  wiki.navigation.warnings.setNewActiveMenu("unsafe-stmt");
});

The render API take an options payload describe by the following TS interface:

export interface RenderDocumentationUIOptions {
  /**
   * Prefetch all flags and cache them
   *
   * @default true
   */
  prefetch?: boolean;
}

Fetch assets required for the bundler

An incomplete example for Vite.

// Import Third-party Dependencies
import { getBuildConfiguration } from "@nodesecure/documentation-ui/node";
import { defineConfig } from "vite";

// Note: all entry points for assets (css etc..).
const { entryPoints } = getBuildConfiguration();

export default defineConfig({
  build: {
    rollupOptions: {
      input: [...entryPoints],
    },
  },
});

API

render(rootElement: HTMLElement, options: RenderDocumentationUIOptions): RenderResult;

Render the documentation in the given root element.

export interface RenderResult {
  header: Header;
  navigation: {
    flags: Navigation;
    warnings: Navigation;
  };
}

Header & Navigation definition

class Header {
  active: HTMLElement;
  views: Map<string, HTMLElement>;
  defaultName: string | null;

  setNewActiveView(name: string): void;
}

class Navigation {
  active: HTMLElement;
  menus: Map<string, HTMLElement>;
  defaultName: string | null;
  prefetch: boolean;
  fetchCallback: (name: string, menu: HTMLElement) => any;

  setNewActiveMenu(name: string): void;
}

How to contribute/work on this project

You can use the local example/ to work on any updates. Just use the example npm script:

$ npm ci
$ npm run example

"scripts": {
  "example": "vite"
}

This starts a Vite dev server with HMR, opening example/demo.html automatically in your browser.

License

MIT