VOC

1.2.0 verified Sat Apr 25 auth: no javascript maintenance

VOC (Very Ornate Code) is a generalized literate programming framework for JavaScript and compile-to-JS languages. It processes Markdown files, extracting code blocks delimited by triple backticks and directing them to specified output files based on hints after the opening backticks. Version 1.2.0 is stable but sees infrequent updates; it supports Node.js >=0.8 and browser usage. Unlike more modern literate programming tools, VOC focuses on simplicity and integration with existing Markdown workflows, offering a preprocessor API for custom language handlers.

Common errors

error TypeError: VOC.run is not a function ↓

cause Incorrect import or missing global object in browser.

fix

Ensure you have loaded VOC properly: use const { VOC } = require('voc'); in Node or include the script tag in browser.

error ReferenceError: VOC is not defined ↓

cause VOC script not included or not loaded in browser.

fix

Add <script src="path/to/voc.js"></script> before using VOC.

error Module not found: Error: Can't resolve 'voc' ↓

cause VOC not installed or not present in node_modules.

fix

Run npm install voc in your project directory.

error SyntaxError: Unexpected token 'export' ↓

cause Using ES module import syntax in a CommonJS environment without transpilation.

fix

Use const { VOC } = require('voc'); instead of import.

Warnings

gotcha VOC relies on third-party libraries (marked.js, coffee-script.js) for browser usage; these are not bundled and must be loaded separately. ↓

fix Include the required scripts before using VOC in a browser.

breaking VOC uses global variables for language handlers. If multiple instances are used, they share state. ↓

fix Avoid using VOC with multiple concurrent scripts; consider using separate scopes or a wrapper function.

deprecated Versions prior to 1.0 had a different API with `VOC.parse` instead of `VOC.run`. The old API is no longer supported. ↓

fix Upgrade to >=1.0.0 and use `VOC.run()`.

gotcha Output files are overwritten without warning. If the same output is specified in multiple code blocks, only the last one is kept. ↓

fix Ensure unique output paths per code block to avoid unintended overwrites.

breaking Node.js engine requirement is >=0.8, which may cause issues on older systems. No support for newer ESM or async features. ↓

fix For modern environments, consider using a newer literate programming tool that supports ESM and async/await.

Install

npm install voc

yarn add voc

pnpm add voc

Imports

VOC
wrong
```
const voc = require('voc');
```
correct
```
import { VOC } from 'voc'
```
VOC exports a global `VOC` object in browsers; for Node.js, use the correct import path. CommonJS require works but returns an object with `run` and `add` methods.
run
wrong
```
const { run } = require('voc');
```
correct
```
import { VOC } from 'voc'; VOC.run(src);
```
`run` is a method of the `VOC` object, not a named export. Destructuring from require may not work as expected.
add
wrong
```
const add = require('voc').add;
```
correct
```
import { VOC } from 'voc'; VOC.add(lang, handler);
```
Similar to `run`, `add` is a method on `VOC`. Direct assignment may cause context issues.

Quickstart

Shows how to use VOC programmatically to process a Markdown file with code blocks.

const { VOC } = require('voc');
const fs = require('fs');
const src = fs.readFileSync('myfile.md', 'utf8');
VOC.run(src);
// The output files are written to the current directory based on the markdown hints.