markdown-it-caml/README.md

Add caml (semantic) attribute syntax for markdown-it.

# markdown-it-caml

[![A WikiBonsai Project](https://img.shields.io/badge/%F0%9F%8E%8B-A%20WikiBonsai%20Project-brightgreen)](https://github.com/wikibonsai/wikibonsai)
[![NPM package](https://img.shields.io/npm/v/markdown-it-caml)](https://npmjs.org/package/markdown-it-caml)

A markdown-it plugin to process [caml](https://github.com/wikibonsai/caml-mkdn) -- Colon Attribute Markup Language.

Note that this plugin only parses the input -- it is up to you to handle and store metadata.

🕸 Weave a semantic web in your [🎋 WikiBonsai](https://github.com/wikibonsai/wikibonsai) digital garden.

## Install

Install with [npm](https://docs.npmjs.com/cli/v9/commands/npm-install):

```
npm install markdown-it-caml
```

## Use

```js
import markdownIt from 'markdown-it';
import caml_plugin from 'markdown-it-caml';

const md = markdownIt();
let opts = {};
md.use(caml_plugin, opts);

md.render(':caml::attribute\n');
```

Require style imports work as well:

```js
const caml_plugin = require('markdown-it-caml');

// if you encounter issues, try:
const caml_plugin = require('markdown-it-caml').default;
```

## Syntax

For syntax specifications, see the [caml-spec](https://github.com/wikibonsai/caml-mkdn/tree/main/spec) repo.

## Options

### `addAttr: (env: any, key: string, value: string) => void`

Called once per collected caml attribute (key/value pair); use for metadata or indexing. `env` is threaded so value-passing works across stages (e.g. recursive embeds). When a co-registered `markdown-it-wikirefs` is present, a wiki-valued attribute is reported with the literal `[[fname]]` as the value and the parsed value is also available on `env.attrs[key]`. Otherwise a plain `'string'`.

### `attrs`

These are options attrbox-specific options.

#### `attrs.enable`

A boolean property that toggles parsing and rendering wikiattrs on/off.

#### `attrs.render`

A boolean property that toggles rendering wikiattrs on/off. This is useful in the scenario where wikiattrs are used for metadata and not for display purposes; like a yaml-stand-in.

### `cssNames`

CSS classnames may be overridden here.

#### `cssNames.attr`

Classname for wikiattrs. Default is `attr`.

#### `cssNames.attrbox`

Classname for the wikiattr attrbox. Default is `attrbox`.