c-md

A transpiler for literate programming in C (and other compiled languages).

Write documentation and code in a single Markdown file. The transpiler extracts the code for compilation while keeping your source readable and well-documented.

Concept

Inspired by Donald Knuth's literate programming, c-md lets you write files like main.c.md that combine Markdown documentation with code blocks. The transpiler extracts the code into pure .c files ready for compilation.

File Format

Source files use the pattern <name>.<ext>.md:

main.c.md   ->  main.c
utils.h.md  ->  utils.h

Example: main.c.md

# Main Entry Point

This file contains the program entry point.
It initializes the system and starts the main loop.

## Dependencies

- stdlib.h for memory allocation
- stdio.h for I/O operations

## Implementation

'''c
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
    printf("Hello, World\n");
    return 0;
}
'''

(Note: Use standard triple backticks ``` in actual files)

Usage

Options

-h, --help            Show help message
-e, --ext <ext>       Extension to extract (c, h, py, etc.)
-i, --input <file>    Input file (default: stdin)
-o, --output <file>   Output file (default: stdout)
-m, --map <file>      Generate line mapping file

Pipe Mode (stdin/stdout)

# Basic transpilation
cat main.c.md | c-md -e c > main.c

# With line mapping
cat main.c.md | c-md -e c -m build/maps/main.map > main.c

File Mode

# Basic transpilation
c-md -i main.c.md -o build/main.c

# With line mapping
c-md -i main.c.md -o build/main.c -m build/maps/main.map

# Extension auto-inferred from filename
c-md -i main.c.md -o build/main.c

Makefile Integration

BUILD_DIR = build
SRC_DIR = src

$(BUILD_DIR)/%.c: $(SRC_DIR)/%.c.md
	c-md -i $< -o $@ -m $(BUILD_DIR)/maps/$*.map

Code Block Filtering

The transpiler extracts only code blocks matching the specified extension.

For file main.c.md with -e c:

• ```c blocks are extracted
• ```python blocks are ignored
• ``` blocks (no language) are ignored

Multiple matching code blocks are concatenated with a blank line separator.

Line Mapping

The transpiler generates .map files that track the correspondence between source lines (.c.md) and output lines (.c). This enables:

• Accurate error reporting back to original files
• IDE/LSP integration (WIP)
• Debugging with correct source locations

Status

v1.0.0 - Initial stable release

License

GPL3