https://github.com/wkillerud/sassdoc-parser
A lightweight parser for SassDoc that supports both Sass syntaxes.
https://github.com/wkillerud/sassdoc-parser
parser sass sassdoc scss
Last synced: 6 months ago
JSON representation
A lightweight parser for SassDoc that supports both Sass syntaxes.
- Host: GitHub
- URL: https://github.com/wkillerud/sassdoc-parser
- Owner: wkillerud
- License: mit
- Created: 2022-05-11T18:20:28.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-09-28T18:15:03.000Z (over 1 year ago)
- Last Synced: 2025-07-14T07:53:47.663Z (7 months ago)
- Topics: parser, sass, sassdoc, scss
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/sassdoc-parser
- Size: 939 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# sassdoc-parser
A lightweight parser for [SassDoc](http://sassdoc.com/). Similar to running `sassdoc --parse`, this parser outputs a structured [data interface](http://sassdoc.com/data-interface/) rather than HTML. This module is designed to be bundled, and can run in the browser.
## Install
```sh
npm install sassdoc-parser
```
## Usage
```ts
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
```ts
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
```ts
import fs from "node:fs/promises";
import { parse } from "sassdoc-parser";
export async function doParse(path: string | string[]): Promise {
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.
```js
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)](/src/types.ts#L87). Check out the snapshot for some example outputs:
- [Example output for SCSS](/src/sassdoc-parser.test.ts)
- [Example output for indented](/src/sassdoc-parser-indented.test.ts)
## 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.
```js
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;
}
`);
```