npm package: @mosajjal/remark-moss
Description: Remark plugin for rendering Moss spreadsheet blocks
Author: Moss Team
Latest version: 1.0.0

# remark-moss

Remark plugin for rendering Moss spreadsheet blocks in MDX and Markdown documents.

## Installation

```bash
npm install remark-moss
# or
pnpm add remark-moss
```

## Usage

### With Remark

```javascript
import { remark } from 'remark';
import remarkMoss from 'remark-moss';
import remarkHtml from 'remark-html';

const markdown = `
# My Document

\`\`\`moss
---
metadata:
  title: "Sales Data"

cells:
  - A1: "Product"
  - B1: "Revenue"
  - A2: "Widget"
  - B2: 1500
  - A3: "Total"
  - B3: =SUM(B2)
\`\`\`
`;

const result = await remark()
  .use(remarkMoss)
  .use(remarkHtml)
  .process(markdown);

console.log(String(result));
```

### With MDX

```javascript
import { compile } from '@mdx-js/mdx';
import remarkMoss from 'remark-moss';

const mdx = `
# Sales Report

\`\`\`moss
---
cells:
  - A1: "Q1"
  - B1: 1500
\`\`\`
`;

const result = await compile(mdx, {
  remarkPlugins: [remarkMoss]
});
```

### With Next.js

```javascript
// next.config.js
import remarkMoss from 'remark-moss';

const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx'],
  experimental: {
    mdxRs: false,
  },
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
    };
    return config;
  },
};

export default nextConfig;

// mdx-components.tsx
import type { MDXComponents } from 'mdx/types';

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    ...components,
  };
}
```

### With Astro

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkMoss from 'remark-moss';

export default defineConfig({
  integrations: [
    mdx({
      remarkPlugins: [remarkMoss],
    }),
  ],
});
```

## Options

```javascript
remarkMoss({
  format: 'html',        // 'html' or 'markdown'
  showErrors: true       // Show error messages in output
});
```

### `format`

- `'html'` (default) - Render as HTML table
- `'markdown'` - Render as markdown table

### `showErrors`

- `true` (default) - Display error messages when Moss parsing fails
- `false` - Silent failures (returns empty string)

## Examples

### Basic Table

````markdown
```moss
---
cells:
  - A1: "Name"
  - B1: "Score"
  - A2: "Alice"
  - B2: 95
```
````

### With Formulas and Charts

````markdown
```moss
---
metadata:
  title: "Quarterly Sales"

cells:
  - A1: "Q1"
  - A2: "Q2"
  - A3: "Q3"
  - A4: "Q4"
  - B1: 1250
  - B2: 1450
  - B3: 1680
  - B4: 1920
  - A5: "Total"
  - B5: =SUM(B1:B4)

visualizations:
  sales_chart:
    type: bar
    title: "Sales by Quarter"
    labels: A1:A4
    data: B1:B4
```
````

### With Display Modes

````markdown
```moss
---
metadata:
  displayMode: paginated
  pageSize: 10

cells:
  # ... many rows ...
```
````

## Features

- ✅ Full Moss syntax support
- ✅ Works with MDX and Markdown
- ✅ Formulas and functions
- ✅ Bar chart visualizations
- ✅ Display modes (paginated, compact, virtual)
- ✅ Error handling
- ✅ TypeScript support
- ✅ Compatible with Next.js, Astro, Docusaurus

## Framework Integration

### Next.js App Router

```typescript
// app/posts/[slug]/page.tsx
import { MDXRemote } from 'next-mdx-remote/rsc';
import remarkMoss from 'remark-moss';

export default async function Post({ params }) {
  const markdown = await getMarkdown(params.slug);

  return (
    <MDXRemote
      source={markdown}
      options={{
        mdxOptions: {
          remarkPlugins: [remarkMoss],
        },
      }}
    />
  );
}
```

### Docusaurus

```javascript
// docusaurus.config.js
const remarkMoss = require('remark-moss');

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          remarkPlugins: [remarkMoss],
        },
        blog: {
          remarkPlugins: [remarkMoss],
        },
      },
    ],
  ],
};
```

### VitePress

```javascript
// .vitepress/config.ts
import { defineConfig } from 'vitepress';
import remarkMoss from 'remark-moss';

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(remarkMoss);
    },
  },
});
```

## Related

- [Moss](https://github.com/moss-lang/moss) - Main Moss project
- [markdown-it-moss](https://github.com/moss-lang/markdown-it-moss) - Markdown-it plugin
- [remark](https://github.com/remarkjs/remark) - Markdown processor

## License

MIT