elseware Docs Engine

A modern React documentation engine built for structured Markdown-based documentation websites with nested routing, sidebar generation, dark mode support, and responsive layouts.

Built with:

• React
• TypeScript 7
• Vite
• React Router
• elseware-ui
• MDXEditor

Features

• Nested documentation structure
• Automatic sidebar generation
• Responsive mobile sidebar
• Markdown rendering
• Code block support
• Dark mode support
• Customizable base path
• TypeScript support
• Vite powered
• Clean documentation layouts

Installation

npm install elseware-docs-engine

Import Styles

import "elseware-docs-engine/dist/index.css";

Basic Usage

import React from "react";

import ReactDOM from "react-dom/client";

import { BrowserRouter, Navigate, Route, Routes } from "react-router-dom";

import {
  DocsEngine,
  DocsPageRenderer,
  useCurrentPage,
} from "elseware-docs-engine";

import docs from "./docs";

import "elseware-docs-engine/dist/index.css";

function Documentation() {
  const page = useCurrentPage();

  return page ? (
    <DocsPageRenderer content={page.content} />
  ) : (
    <Navigate to="/docs/getting-started/intro" replace />
  );
}

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <BrowserRouter>
      <DocsEngine docs={docs} basePath="/docs">
        <Routes>
          <Route path="/docs/*" element={<Documentation />} />
        </Routes>
      </DocsEngine>
    </BrowserRouter>
  </React.StrictMode>,
);

When deploying this as a single-page application, configure the host to rewrite document requests to index.html so direct links and browser reloads reach React Router.

Docs Structure Example

import intro from "./getting-started/intro.md?raw";

import { DocsCategory } from "elseware-docs-engine";

const docs: DocsCategory[] = [
  {
    title: "Getting Started",

    path: "/getting-started",

    children: [
      {
        title: "Introduction",

        path: "/intro",

        content: intro,
      },
    ],
  },
];

export default docs;

Markdown Features

• Headings
• Tables
• Lists
• Images
• Links
• Quotes
• Code blocks
• Syntax highlighting
• Nested navigation

Development

Pull requests targeting main run the complete validation suite and verify that the package version has not already been published. A successful merge to main runs the same checks and publishes through GitHub's OIDC trusted publishing; no long-lived npm token is stored in GitHub. Because this source repository is private, npm provenance is disabled.

Configure npm Trusted Publishing for elseware-docs-engine using repository elsewaretechnology/elseware-docs-engine, workflow publish.yml, and the GitHub environment npm-production. Keep package.json and package-lock.json synchronized and bump the version in the release PR:

npm version patch --no-git-tag-version

The workflow fails when the exact version already exists on npm. If the repository becomes public, remove --provenance=false to enable provenance.

npm install
npm run dev

Code quality

npm run typecheck        # TypeScript 7 project check
npm run lint             # TypeScript and React rules with Oxlint
npm run format:check
npm run deadcode
npm run build            # ESM, CommonJS, CSS, and declarations
npm run validate         # Every quality gate and the production build

TypeScript 7 is the only compiler dependency. tsup bundles JavaScript and CSS, then the TypeScript 7 CLI emits the declaration files. Oxlint provides TypeScript and React linting without relying on the removed legacy compiler API.

Staged source files are linted and formatted automatically by the Husky pre-commit hook.

License

MIT License

Author

elseware Technology