include_code

A powerful remark plugin that automatically includes code snippets from source files in your markdown documentation. Perfect for keeping your documentation in sync with your actual codebase.

Features

• 📝 Include code snippets with simple markdown macros
• 🚀 Built-in caching for fast rebuilds
• 🔍 Auto-detection of Git repository information
• ✅ Validation modes to catch missing snippets
• 🎨 Syntax highlighting support
• 🔗 Automatic source links to GitHub
• 📦 Framework agnostic - works with any remark-based tool (Vocs, Docusaurus, Nextra, etc.)

Installation

npm install include_code
# or
yarn add include_code
# or
pnpm add include_code

Quick Start

1. Mark your code

Add special comments in your source code to mark the snippets you want to include:

// src/example.ts

// docs:start:hello-world
export function hello(name: string): string {
  return `Hello, ${name}!`;
}
// docs:end:hello-world

2. Configure the plugin

// vocs.config.ts (or similar)
import { defineConfig } from 'vocs';
import { remarkIncludeCode } from 'include_code';

export default defineConfig({
  markdown: {
    remarkPlugins: [
      [remarkIncludeCode, {
        codeDir: './src',          // Where your source code lives
        docsDir: './docs',         // Where your docs live (optional)
        cache: true,               // Enable caching for faster rebuilds
        validation: 'warn',        // Warn about missing snippets
      }]
    ]
  }
});

3. Use in your markdown

# My Documentation

Here's an example function:

#include_code hello-world /example.ts typescript

This will be replaced with:

```typescript title="hello-world" showLineNumbers
export function hello(name: string): string {
  return `Hello, ${name}!`;
}
```
<sup><sub><a href="https://github.com/owner/repo/blob/master/src/example.ts#L3-L5" target="_blank">Source code: /example.ts#Lhello-world</a></sub></sup>

Macro Syntax

The basic macro format is:

#include_code <identifier> <filepath> <language> [options]

• identifier: The marker name used in your source code (e.g., hello-world)
• filepath: Relative path to the source file from codeDir (e.g., /example.ts)
• language: Programming language for syntax highlighting (e.g., typescript, rust, python)
• options: Optional flags (see below)

Options

You can combine multiple options separated by commas or colons:

• noTitle - Don't show the title in the code block
• noLineNumbers - Don't show line numbers
• noSourceLink - Don't show the source link below the code

Example:

#include_code my-snippet /file.ts typescript noTitle,noLineNumbers

Configuration

IncludeCodeOptions

interface IncludeCodeOptions {
  /** Root directory of the source code files (required) */
  codeDir: string;

  /** Root directory of the documentation files (optional, defaults to cwd) */
  docsDir?: string;

  /** Repository information (optional - auto-detected if not provided) */
  repository?: {
    owner: string;          // e.g., 'myorg'
    name: string;           // e.g., 'myrepo'
    baseUrl?: string;       // e.g., 'https://github.com' (default)
  };

  /** Git commit tag/branch/SHA for source links (default: 'master') */
  commitTag?: string;

  /** Cache configuration (default: true) */
  cache?: boolean | {
    enabled: boolean;
    directory: string;      // default: '.include-code-cache'
    ttl?: number;          // time-to-live in ms (optional)
  };

  /** Validation mode (default: 'warn') */
  validation?: 'off' | 'warn' | 'error';

  /** Default language when not specified (optional) */
  defaultLanguage?: string;

  /** Custom marker configuration */
  markers?: {
    start: string;         // default: 'docs:start'
    end: string;           // default: 'docs:end'
  };
}

Example Configurations

Basic Setup

[remarkIncludeCode, {
  codeDir: './src'
}]

With Custom Repository

[remarkIncludeCode, {
  codeDir: './packages/core/src',
  repository: {
    owner: 'myorg',
    name: 'myrepo'
  },
  commitTag: 'v1.0.0'
}]

Strict Validation

[remarkIncludeCode, {
  codeDir: './src',
  validation: 'error',  // Fail build on missing snippets
  cache: {
    enabled: true,
    directory: '.cache/include-code',
    ttl: 3600000  // 1 hour
  }
}]

Custom Markers

[remarkIncludeCode, {
  codeDir: './src',
  markers: {
    start: 'snippet:begin',
    end: 'snippet:finish'
  }
}]

Then in your code:

// snippet:begin:my-function
function myFunction() {
  // ...
}
// snippet:finish:my-function

Advanced Features

Multiple Snippets in One File

You can have multiple, even overlapping, code snippets in a single file:

// docs:start:full-example
export class Calculator {
  // docs:start:add-method
  add(a: number, b: number): number {
    return a + b;
  }
  // docs:end:add-method

  // docs:start:subtract-method
  subtract(a: number, b: number): number {
    return a - b;
  }
  // docs:end:subtract-method
}
// docs:end:full-example

Caching

The plugin includes a smart caching system that:

• Stores extracted snippets on disk
• Invalidates cache when source files change
• Significantly speeds up rebuilds for large codebases

Cache is enabled by default. To disable:

[remarkIncludeCode, {
  codeDir: './src',
  cache: false
}]

Validation Modes

Control how the plugin handles errors:

• off: Silently ignore missing snippets (not recommended)
• warn: Log warnings but continue build (default)
• error: Fail build on any missing snippet (recommended for CI)

Use Cases

Documentation Sites

Keep your docs in sync with your code automatically:

Here's how to use our API:

#include_code api-usage /examples/api.ts typescript

Tutorials

Show step-by-step code without duplication:

## Step 1: Setup

#include_code setup-code /tutorial/step1.ts typescript

## Step 2: Add Features

#include_code features-code /tutorial/step2.ts typescript

API References

Pull type definitions directly from source:

## Types

#include_code user-type /types/user.ts typescript

Migration from Previous Versions

If you're migrating from the local implementation, here's what changes:

Before

import { remarkIncludeCode } from './src/plugins/remark-include-code';

[remarkIncludeCode, {
  rootDir: path.join(__dirname, 'submodules/aztec-packages'),
  commitTag: process.env.COMMIT_TAG
}]

After

import { remarkIncludeCode } from 'include_code';

[remarkIncludeCode, {
  codeDir: path.join(__dirname, 'submodules/aztec-packages'),
  docsDir: __dirname,  // optional
  commitTag: process.env.COMMIT_TAG,
  cache: true,         // new feature!
  validation: 'warn'   // new feature!
}]

Troubleshooting

Snippet not found

Error: Identifier "my-snippet" not found in file "/path/to/file.ts"

• Check that your markers are correctly placed in the source file
• Verify the file path is correct relative to codeDir
• Make sure you're using the correct marker format (docs:start:identifier)

Repository not detected

If source links aren't appearing:

• Ensure your codeDir is inside a git repository
• Or manually provide repository information in options

Cache issues

If you're seeing stale content:

• Delete the .include-code-cache directory
• Or disable caching temporarily with cache: false

Contributing

Contributions are welcome! Please open an issue or PR on GitHub.

License

MIT

Credits

A remark plugin for including code snippets in documentation.