README.md

sassdoc-parser

A lightweight parser for SassDoc. Similar to running sassdoc --parse, this parser outputs a structured data interface rather than HTML. This module is designed to be bundled, and can run in the browser.

Install

npm install sassdoc-parser

Usage

import { parse } from "sassdoc-parser";

async function doParse() {
  const result = await parse(`
/// Keeps it secret
/// @output Sets display to hidden
@mixin _keep-it-secret {
  display: hidden;
}
`);

doParse();

Or sync

import { parseSync } from "sassdoc-parser";

const result = parseSync(`
/// Keeps it secret
/// @output Sets display to hidden
@mixin _keep-it-secret {
  display: hidden;
}
`);

Parse using paths

import fs from "node:fs/promises";
import { parse } from "sassdoc-parser";

export async function doParse(path: string | string[]): Promise<ParseResult[]> {
	const paths = Array.isArray(path) ? path : [path];
	const result = await Promise.all(
		paths.map(async (src) => {
			const code = await fs.readFile(src, "utf-8");
			return await parse(code);
		}),
	);
	return result.flat();
}

const singlePathResult = await doParse("_helpers.scss");
const arrayOfPathsResult = await doParse(["_mixins.scss", "_functions.scss"]);

Indented syntax

The parser can handle indented syntax with a caveat:

• The context field will not include accurate code or line fields.

import { parseSync } from "sassdoc-parser";

const result = parseSync(
	`
/// Converts a value to the given unit
/// @param {Number} $value - Value to add unit to
/// @param {String} $unit - String representation of the unit
/// @return {Number} - $value expressed in $unit
@function to-length($value, $unit)
	$units: (
		"px": 1px,
		"rem": 1rem,
		"%": 1%,
		"em": 1em,
	)

	@if not index(map-keys($units), $unit)
			$_: log("Invalid unit #{$unit}.")

	@return $value * map.get($units, $unit)
`,
);

Output

The result from the parse function is an array of ParseResult (type definitions). Check out the snapshot for some example outputs:

• Example output for SCSS
• Example output for indented

Advanced usage

If you're running this parser on a hot code path, you might discover a noticable time is spent constructing the Parser class. The parse and parseSync methods create a new instance of this parser for each invocation. To reuse the same parser instance, import the Parser class and use that instead.

import { Parser } from "sassdoc-parser";

const parser = new Parser();

const result = await parser.parseString(`
/// Keeps it secret
/// @output Sets display to hidden
@mixin _keep-it-secret {
  display: hidden;
}
`);

const syncResult = parser.parseStringSync(`
/// Keeps it secret
/// @output Sets display to hidden
@mixin _keep-it-secret {
  display: hidden;
}
`);