npm package: @mintlify/msft-sdk
Description: Lightweight SDK for Microsoft documentation with MDX rendering
Author: Mintlify, Inc.
Latest version: 1.1.72

# @mintlify/msft-sdk

Lightweight SDK for rendering Microsoft-style documentation with MDX support.

## Installation

```bash
npm install @mintlify/msft-sdk
```

## Quick Start

### 1. Import Styles

```tsx
import "@mintlify/msft-sdk/styles.css";
```

Optional: Add dark mode support with Tailwind CSS:

```css
@variant dark (&:where(.dark, .dark *));
```

### 2. Convert HTML to MDX

```tsx
import { convertHtmlToMdx, serializeMdx } from "@mintlify/msft-sdk";

const { mdx, mdxExtracts } = await convertHtmlToMdx(htmlContent, {
  metadata: { title: "My Doc" },
});

const Content = await serializeMdx(mdx);
```

### 3. Render Documentation

```tsx
import { DocsPage } from "@mintlify/msft-sdk";

<DocsPage
  payload={{
    serializedContent: Content,
    title: "Documentation",
    mdxExtracts,
  }}
  toc={tocItems}
  navTree={navTree}
/>;
```

## Core Exports

### Documentation Components
- `DocsPage` - Main documentation page component
- `ApiPage` - API reference page component
- `DocsLayout` - Layout with navigation sidebar
- `MDXRenderer` - Standalone MDX renderer
- `NavTree`, `TableOfContents` - Navigation components
- `allComponents` - All available MDX components

### Content Processing
- `convertHtmlToMdx` - Convert HTML to MDX
- `serializeMdx` - Compile MDX to React components

### OpenAPI Utilities
- `convertOpenApiSpecToGraph` - Convert OpenAPI spec to schema graph data
- `convertOpenApiSpecToNav` - Generate navigation structure from OpenAPI spec
- `convertOpenApiSpecToHrefMap` - Create href-to-endpoint lookup map

## OpenAPI Integration

The SDK provides utilities for working with OpenAPI specifications:

```tsx
import {
  convertOpenApiSpecToGraph,
  convertOpenApiSpecToNav,
  convertOpenApiSpecToHrefMap,
  getApiReferenceDataFromGraph,
  ApiPage,
} from "@mintlify/msft-sdk";
import openApiSpec from "./my-openapi-spec.json";

// Convert spec to schema graph (required for API rendering)
const graphData = convertOpenApiSpecToGraph(openApiSpec, {
  filename: "my-api.json",
  originalFileLocation: "my-api.json",
});

// Generate navigation from OpenAPI spec
const navData = convertOpenApiSpecToNav(openApiSpec);

// Create href-to-endpoint map for routing
const hrefMap = convertOpenApiSpecToHrefMap(openApiSpec);

// Get API reference data for a specific endpoint
const apiReferenceData = getApiReferenceDataFromGraph({
  metadata: {
    title: "Create User",
    description: "Create a new user",
    openapi: "post /users",
  },
  schemaGraphData: graphData,
});

// Render the API page
<ApiPage
  apiReferenceData={apiReferenceData}
  pageMetadata={metadata}
  theme="light"
/>;
```

## Development

### Running Tests

This project uses [Vitest](https://vitest.dev/) for testing.

```bash
# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

### Test Structure

Tests are located in the `tests/` directory and are organized as follows:

- `tests/fixtures/` - Test fixtures including OpenAPI specs and expected outputs
- `tests/*.test.ts` - Test files for various conversion functions

The test fixtures are kept outside of the `src/` directory to ensure they're not bundled with the package.

## License

MIT © Mintlify, Inc.