mdxai

mdxai is a command-line interface (CLI) tool and JavaScript library designed to generate and edit MDX files using AI. It integrates structured data, unstructured content, executable code, and UI components into a unified workflow, leveraging OpenAI's API to streamline content creation and modification.

Features

• Structured Data: Supports YAML frontmatter for metadata.
• Unstructured Content: Handles markdown for text content.
• Executable Code: Allows JavaScript/TypeScript imports and exports.
• UI Components: Integrates JSX/React components seamlessly.
• AI-Powered Assistance: Generates and edits content using OpenAI's API.
• Customizable Templates: Provides templates for various use cases.
• AI Functionality: Execute MDX AI functions to generate dynamic content.
• TypeScript Integration: Automatically generates TypeScript types for AI functions based on MDX frontmatter.

Installation

Install mdxai globally using npm:

npm install -g mdxai

Alternatively, use it without installation via npx:

npx mdxai <command>

To use the JavaScript/TypeScript API, install as a local dependency:

npm install mdxai

CLI Usage

Prerequisites

1. Ensure you have an OpenAI API key. Set it as an environment variable:

   export OPENAI_API_KEY=your-api-key

2. Verify that Node.js is installed (version 14 or later).

Commands

mdxai

The mdxai command serves as a unified entry point for generating content, executing functions, and editing MDX files.

Generate or Execute

Generate or execute AI-driven MDX content:

mdxai blog/using-large-language-models

This command will infer the context, stream the output to the console, and save the result to:

/output/blog/using-large-language-models.mdx

Specify Output Location

Optionally, specify a custom output location:

mdxai blog/using-large-language-models --output custom-path/output.mdx

Edit an Existing File

Edit an existing MDX file:

mdxai edit my-blog-post.mdx

List Templates

List available templates:

mdxai templates

Help

For detailed usage instructions:

mdxai help

API Usage

mdxai exports a JavaScript object ai that allows you to programmatically interact with AI functions defined in the ./ai directory.

Example: Writing a Blog Post

Create a file ./ai/writeBlogPost.mdx:

---
model: gpt-4
system: 'You are a helpful assistant.'
input: string
output: string
---

Generate a blog post about `{input}`. The content should be engaging and informative.

Use the ai object in your code:

import { ai } from 'mdxai'

async function main() {
  const result = await ai.writeBlogPost('about dogs')
  console.log(result)
}

main()

If the file ./ai/writeBlogPost.mdx does not exist, it will be automatically created with default content.

Frontmatter in AI Files

• model: Specifies the AI model to use (e.g., gpt-4).
• system: Defines the system message for the AI.
• input: Defines the type of input (string by default).
• output: Defines the shape of the output (string by default). Can be an object type for structured responses.

Example with object output:

---
model: gpt-4
system: 'You are a helpful assistant.'
input: string
output:
  title: string
  content: string
---

Generate a blog post about `{input}` with a title and detailed content.

Corresponding TypeScript types will be automatically generated:

type AI = {
  writeBlogPost: (input: string) => Promise<{
    title: string
    content: string
  }>
}

Examples

Execute AI Function

mdxai writeBlogPost about dogs

The result will stream to the console and save to:

/output/writeBlogPost/about-dogs.mdx

Generate and Save Content

mdxai blog/using-large-language-models

Edit an Existing File

mdxai edit my-blog-post.mdx

List Templates

mdxai templates

Templates

mdxai includes a variety of templates tailored for specific use cases:

• Blog Posts: Structured layouts for blogging.
• Documentation: Clean, developer-friendly documentation templates.
• Tutorials: Step-by-step guides with code snippets.
• UI Components: Templates for creating reusable React components.
• APIs: Define and export functions using the WHATWG fetch API.
• General Functions: Export utility or custom functions.

Examples of MDX Files

UI Components

---
$type: https://mdx.org.ai/UIComponent
---

import { Button } from 'https://esm.sh/@mui/material/Button'

<Button onClick={() => alert('Hello, world!')}>Click Me</Button>

APIs

---
$type: https://schema.org/APIReference
---

This function fetches data from a given URL and returns the JSON response.

```js
export const fetch = (request) => Response.json({ hello: 'world ' })
```

General Functions

---
$type: https://schema.org/Function
---

export const greet = (name) => `Hello, ${name}!`

This function greets the provided name with a friendly message.

Environment Variables

• OPENAI_API_KEY: Your API key for OpenAI. Required for AI features.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Submit a pull request with a detailed description of your changes.

License

mdxai is licensed under the MIT License.

Start creating smarter MDX content with mdxai today!