@tryfabric/martian

The library provides a list of languages supported for Notion code blocks. Use isSupportedCodeLang(lang: string) to validate if a specific language string is supported by the Notion API via this library.

Supported languages include typescript, javascript, python, rust, go, sql, markdown, and many others.

import { isSupportedCodeLang } from './notion/common';

console.log(isSupportedCodeLang('typescript')); // true
console.log(isSupportedCodeLang('unknown-lang')); // false

The parseCalloutEmoji function inspects a string to determine if it starts with an emoji. If an emoji is detected at the beginning of the first line, it returns an object containing the emoji itself (as an EmojiRequest) and a corresponding Notion ApiColor determined by the SUPPORTED_EMOJI_COLOR_MAP. If no emoji is found at the start of the text, it returns null.

import { parseCalloutEmoji } from '@tryfabric/martian/notion';

const result = parseCalloutEmoji('🚀 This is a callout');
if (result) {
  console.log(result.emoji); // '🚀'
  console.log(result.color); // The mapped ApiColor
}

Use markdownToBlocks() to transform a full Markdown or GitHub Flavored Markdown (GFM) string into an array of Notion Block objects. This function supports GFM and mathematical notation via remark-math. It uses unified with remark-parse, remark-gfm, and remark-math under the hood to process the input.

import { markdownToBlocks } from '@tryfabric/martian';

const markdown = '# Hello\nThis is a block.';
const blocks = markdownToBlocks(markdown);
// returns notion.Block[]

To create a table in Notion, you must use a combination of table, tableRow, and RichText arrays for cells.

1. Use tableRow(cells) where cells is an array of RichText[] (one array per cell in the row).
2. Use table(children, tableWidth) where children is an array of the rows created above.

import { table, tableRow, richText } from './notion/blocks';

const row1 = tableRow([
  [richText('Cell 1')],
  [richText('Cell 2')]
]);

const row2 = tableRow([
  [richText('Cell 3')],
  [richText('Cell 4')]
]);

const myTable = table([row1, row2], 100);

Use markdownToRichText() to transform inline Markdown or GFM content into an array of Notion RichText objects. This is intended for parsing text segments that reside within a block.

Supported formatting:

• Plain text
• Italics
• Bold
• Strikethrough
• Inline code
• Hyperlinks

import { markdownToRichText } from '@tryfabric/martian';

const inlineMd = '**bold text** and *italics*';
const richText = markdownToRichText(inlineMd);
// returns notion.RichText[]

Use the richText function to construct Notion-compatible RichText objects. You can specify the content, the type ('text' or 'equation'), and various annotations like bold, italic, color, etc. If a valid URL is provided in the options.url field, it will be automatically applied as a link to the text.

Supported type values:

• 'text' (default)
• 'equation'

Supported annotations:

• bold?: boolean
• italic?: boolean
• strikethrough?: boolean
• underline?: boolean
• code?: boolean
• color?: string

import { richText } from './notion/common';

// Create basic text
const text = richText('Hello World');

// Create bold, blue text with a link
const styledLink = richText('Click me', {
  annotations: { bold: true, color: 'blue' },
  url: 'https://example.com'
});

// Create an equation
const equation = richText('e=mc^2', { type: 'equation' });

The parseCodeLanguage function takes a string representing a programming language and attempts to map it to a supportedCodeLang type. It performs a case-insensitive lookup against an internal language map. If the language is not recognized or no string is provided, it returns undefined.

import { parseCodeLanguage } from '@tryfabric/martian/notion';

const lang = parseCodeLanguage('typescript');
// returns the corresponding supportedCodeLang type

The library supports GitHub Flavored Markdown (GFM) alert types, which can be mapped to specific Notion emojis and background colors.

Supported GfmAlertType values:

• NOTE (Emoji: 📘, Color: blue_background)
• TIP (Emoji: 💡, Color: green_background)
• IMPORTANT (Emoji: ☝️, Color: purple_background)
• WARNING (Emoji: ⚠️, Color: yellow_background)
• CAUTION (Emoji: ❗, Color: red_background)

Use isGfmAlertType(type: string) to validate a type and GFM_ALERT_MAP to retrieve the corresponding emoji and color configuration.

import { GFM_ALERT_MAP, isGfmAlertType } from './notion/common';

const type = 'WARNING';
if (isGfmAlertType(type)) {
  const config = GFM_ALERT_MAP[type];
  console.log(config.emoji); // '⚠️'
  console.log(config.color); // 'yellow_background'
}

When constructing payloads for the Notion API, ensure you stay within these defined limits to avoid errors:

import { LIMITS } from './notion/common';

console.log(LIMITS.PAYLOAD_BLOCKS); // 1000