Skip to the content.
🐤 Documentation and Wiki UI 👀
## 📢 About
Portable documentation/wiki UI for NodeSecure tools like [CLI](https://github.com/NodeSecure/cli) or [Preview](https://github.com/NodeSecure/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](https://github.com/NodeSecure/flags/blob/main/FLAGS.md) using the package `@nodesecure/flags`.
- Render [NodeSecure JS-X-RAY SAST Warnings](https://github.com/NodeSecure/js-x-ray).
> [!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](https://github.com/markdown-it/markdown-it#readme) as dependency).
## 💃 Getting Started
This package is available in the Node Package Repository and can be easily installed with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or [yarn](https://yarnpkg.com).
```bash
$ npm i @nodesecure/documentation-ui
# or
$ yarn add @nodesecure/documentation-ui
```
## 👀 Usage example
```js
// 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:
```ts
export interface RenderDocumentationUIOptions {
/**
* Prefetch all flags and cache them
*
* @default true
*/
prefetch?: boolean;
}
```
### Fetch assets required for the bundler
An incomplete example for Vite.
```ts
// 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.
```ts
export interface RenderResult {
header: Header;
navigation: {
flags: Navigation;
warnings: Navigation;
};
}
```
Header & Navigation definition
```ts
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;
}
```