Markdown Processing

/**
 * Create a markdown processor with VuePress plugins
 * @param {object} markdown - Configuration options
 * @returns {MarkdownIt} Enhanced markdown-it instance with VuePress plugins
 */
function createMarkdown(markdown?: MarkdownConfig): MarkdownIt;

const createMarkdown = require('@vuepress/markdown');

// Basic usage with default configuration
const md = createMarkdown();
const result = md.render('# Hello World');
console.log(result.html);        // '<h1 id="hello-world"><a class="header-anchor" href="#hello-world">#</a> Hello World</h1>'
console.log(result.data);        // Plugin data collected during rendering
console.log(result.dataBlockString); // Serialized data block for Vue components

// With custom configuration
const mdCustom = createMarkdown({
  lineNumbers: true,
  anchor: {
    permalink: true,
    permalinkSymbol: '🔗'
  },
  toc: {
    includeLevel: [1, 2, 3]
  },
  externalLinks: {
    target: '_blank',
    rel: 'noopener noreferrer'
  }
});

// With custom plugins
const mdWithPlugins = createMarkdown({
  plugins: [
    ['markdown-it-custom-plugin', { option: 'value' }]
  ]
});

// Real-world VuePress documentation processing
const vuepressMarkdown = createMarkdown({
  lineNumbers: true,
  anchor: {
    permalink: true,
    permalinkBefore: true,
    permalinkSymbol: '#'
  },
  toc: {
    includeLevel: [2, 3, 4],
    format: headers => headers
  },
  externalLinks: {
    target: '_blank',
    rel: 'noopener noreferrer'
  },
  beforeInstantiate(config) {
    // Remove plugins we don't need
    config.plugins.delete('emoji');
  },
  afterInstantiate(md) {
    // Add custom functionality
    md.use(require('markdown-it-task-lists'));
  }
});

// Process documentation with components and code snippets
const docContent = `
# API Reference

<Badge text="v1.9.10" type="warning"/>

## Overview

This module provides markdown processing capabilities.

\`\`\`js{1,3-4}
const createMarkdown = require('@vuepress/markdown');
const md = createMarkdown();
const result = md.render('# Hello');
console.log(result.html);
\`\`\`

<<< @/examples/basic-usage.js{js}

[[toc]]
`;

const result = vuepressMarkdown.render(docContent);
console.log('Generated HTML:', result.html);
console.log('Component data:', result.data);

/**
 * Enhanced render method that returns HTML and data
 * @param {string} src - Markdown source content
 * @param {object} env - Environment object
 * @returns {RenderResult} Object containing html, data, and dataBlockString
 */
render(src: string, env?: object): RenderResult;

interface RenderResult {
  html: string;           // Rendered HTML content
  data: object;          // Plugin data collected during rendering
  dataBlockString: string; // Serialized data block for Vue components
}

const md = createMarkdown();

// Render markdown with data collection
const result = md.render(`
# My Document

<MyComponent :data="{ title: 'Hello' }" />

\`\`\`js{1,3}
console.log('line 1');
console.log('line 2');
console.log('line 3');
\`\`\`
`);

console.log(result.html);        // Rendered HTML
console.log(result.data);        // Plugin data (component info, etc.)
console.log(result.dataBlockString); // Serialized data for Vue

/**
 * Enhance markdown-it instance to return data with HTML
 * @param {MarkdownIt} md - markdown-it instance to enhance
 */
function dataReturnable(md: MarkdownIt): void;

/**
 * Slugify function attached to markdown-it instance
 * @param {string} str - String to slugify
 * @returns {string} Slugified string suitable for anchors
 */
md.slugify(str: string): string;

const md = createMarkdown();

// Access the slugify function
const slug = md.slugify('Hello World!'); // 'hello-world'
const customSlug = md.slugify('API Reference 2.0'); // 'api-reference-2-0'

interface MarkdownConfig {
  /** Configuration for external link handling */
  externalLinks?: ExternalLinksConfig;
  /** Page suffix for router link conversion */
  pageSuffix?: string;
  /** Anchor plugin configuration */
  anchor?: AnchorConfig;
  /** Table of contents plugin configuration */
  toc?: TocConfig;
  /** Additional markdown-it plugins to load */
  plugins?: Plugin[];
  /** Enable line numbers in code blocks */
  lineNumbers?: boolean;
  /** Custom slugify function for anchors */
  slugify?: (str: string) => string;
  /** Hook called before markdown-it instantiation */
  beforeInstantiate?: (config: ChainConfig) => void;
  /** Hook called after markdown-it instantiation */
  afterInstantiate?: (md: MarkdownIt) => void;
}

/**
 * Hook called before markdown-it is instantiated
 * @param {object} config - markdown-it-chain configuration object
 */
beforeInstantiate?: (config: ChainConfig) => void;

/**
 * Hook called after markdown-it is instantiated
 * @param {MarkdownIt} md - The created markdown-it instance
 */
afterInstantiate?: (md: MarkdownIt) => void;

const md = createMarkdown({
  beforeInstantiate(config) {
    // Modify configuration before instantiation
    config.plugin('my-custom-plugin')
      .use(myPlugin, [{ option: 'value' }]);
  },
  afterInstantiate(md) {
    // Modify the instance after creation
    md.customProperty = 'custom value';
    md.use(anotherPlugin);
  }
});