docmark

comment parser with support for markdown, positional info, and concrete tokens.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
• Extensions
  • List of extensions
  • Extension
  • Extending docdown
  • Creating a docmark extension
• Architecture
  • Overview
  • Preprocess
  • Parse
  • Postprocess
• Examples
  • Directives
  • GitHub flavored markdown (GFM)
  • Math
  • Syntax tree
• Docdown
  • CommonMark
  • Grammar
• Project
  • Version
  • Contribute
  • Sponsor
  • Origin

What is this?

docmark is an open source comment parser with support for markdown written in TypeScript.
The parser is implemented as a state machine that emits concrete tokens with positional info.
External tools and libraries can turn these tokens into different things.

When should I use this?

TODO: when should i use this?

Install

This package is ESM only.

In Node.js (version 22+) with yarn:

yarn add @flex-development/docmark

See Git - Protocols | Yarn  for details regarding installing from Git.

In Deno with esm.sh:

import { parse, postprocess, preprocess } from 'https://esm.sh/@flex-development/docmark'

In browsers with esm.sh:

<script type="module">
  import { parse, postprocess, preprocess } from 'https://esm.sh/@flex-development/docmark'
</script>

Use

TODO: use

API

See § API in the docmark readme.

Extensions

docmark supports extensions.
Extensions change how comments are parsed.

Extension

A syntax extension is an object whose fields are typically the names of hooks, referring to where constructs "hook" into. The fields at such objects are character codes, mapping to constructs as values, while other fields provide parser configuration or additional behavior.

The builtin extensions are an example.
See them and existing extensions for inspiration.

List of extensions

• @flex-development/docmark-extension-hashbang — support hasbang comment syntax
• @flex-development/docmark-extension-js — support javascript comment syntax
• @flex-development/docmark-extension-jsonc — support json comment syntax
• @flex-development/docmark-extension-sass — support sass comment syntax
• @flex-development/docmark-extension-shell — support shell comment syntax
• @flex-development/docmark-extension-ts — support typescript comment syntax
• @flex-development/docmark-extension-yaml — support yaml comment syntax

Extending docdown

TODO: extending docdown

Creating a docmark extension

TODO: creating a docmark extension

Architecture

Overview

TODO: overview

Preprocess

TODO: preprocess

Parse

TODO: parse

Postprocess

TODO: postprocess

Examples

Directives

TODO: directives

GitHub flavored markdown (GFM)

TODO: github flavored markdown (gfm)

Math

TODO: math

Syntax tree

TODO: syntax tree

Docdown

CommonMark

TODO: commonmark

Grammar

TODO: grammar

Project

Version

docmark adheres to semver.

Contribute

See CONTRIBUTING.md.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Sponsor

Consider sponsoring to support maintenance, tests, and long-term stability!

Origin

TODO: origin