@mintlify/msft-sdk

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

Installation

npm install @mintlify/msft-sdk

Quick Start

1. Import Styles

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

Optional: Add dark mode support with Tailwind CSS:

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

2. Convert HTML to MDX

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

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:

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 for testing.

# 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.