remark-moss

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

Installation

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

Usage

With Remark

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

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

// 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

// 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

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

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

With Formulas and Charts

```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

```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

// 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

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

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

VitePress

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

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

Related

• Moss - Main Moss project
• markdown-it-moss - Markdown-it plugin
• remark - Markdown processor

License

MIT