npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ulu/sassdoc-to-markdown

v0.0.15

Published

A flexible SCSS documentation tool that generates clean, customizable Markdown from your Sass stylesheets. It leverages SassDoc for data extraction and offers various configuration options to tailor the output to your specific needs

Downloads

87

Readme

Sassdoc To Markdown

A flexible SCSS documentation tool that generates clean, customizable Markdown from your Sass stylesheets. It leverages SassDoc for data extraction and offers various configuration options to tailor the output to your specific needs.

  • Compiled Sass examples (Dart Sass), with the ability to configure custom compiler
  • Preview (output) HTML examples
  • Content blocks between documented items (ie. generic content not tied to a specific annotation)
  • Compiled examples can be configured to use your own implementation, see options (ie. if using node-sass for example)
  • Custom group display names by adding dash ie /// @group util - Shared Utilities
  • Group descriptions pulled from lines after group definition (you can also use content blocks to describe groups)
  • Ability to override all annotation and page templates and add your own custom annotations

Table of Contents

Examples

Example of Using this Library

import { resolve, dirname } from "path";
import { fileURLToPath } from "url";
import { outputPages } from "@ulu/sassdoc-to-markdown";

const __dirname = dirname(fileURLToPath(import.meta.url));

(async () => {
  await outputPages({
    dist: resolve(__dirname, "docs/"),
    dir: resolve(__dirname, "src/sass/"),
    pathBase: "/sass/"
  });
})();

Compiled Sassdoc Example

/// In addition to the code block example this example will show the compiled result. Note the  {compile} modifier on the example. It also uses the compiler annotation to load the module for the compiled example. Content in the compiler annotation are prepended to the compiled code for the item or group if at file-level)
/// @compiler
///   @use "_this-file" as examples;
/// @example scss {compile} This example will be compiled
///   @include examples.print-color(red);

@mixin  print-color($value) {
  .test {
    color: $value;
  }
}

Preview HTML Example

/// In addition to the html example this will also be previewed in an iframe. Note the {preview} modifier. Settings are available to add stylesheet and javascript to iframe. Iframe used for isolation from docs styles. 
/// @example html {preview} This example will be previewed
///   <span class="test">This is a test</span>

@mixin  some-mixin($value) {
  .test {
    color: red;
  }
}

Configuration

The following options can be passed to configure this generator. Also you can see the full defaults at /lib/defaults.js.

| Name | Type | Default Value | Description | |---|---|---|---| | dist | string | "" | The directory to output documentation pages | | dir | string | "" | The directory that sassdocs will parse and make pages from | | debug | boolean | false | Plugin development flag (output logs, etc) | | debugToDir | string | null | Print out plugin/sassdoc data (used for developing plugin) | | pathBase | string | "/sass/" | Path to prefix to all paths generated for sassdocs | | byType | boolean | true | Whether or not the documented items should be organized by type (variable, mixin, etc) or should display in the order they were parsed | | sassdocOptions | object | { verbose: true } | Sassdoc library options | | contentEnabled | boolean | true | Include comment blocks that are between sassdoc items | | contentInline | boolean | true | Extra content should all be displayed above items (ie. variables, mixins, etc) even if it is in between documented items | | previewEnabled | boolean | true | Output preview of html code from an example | | previewTemplate | function | (code, ctx) => <div>\n${ code }\n</div> | Template to use for html previews | | previewTitle | string | "Preview" | Title for preview | | undefinedGroupName | string | "None" | Name for undefined groups | | annotations | string[] | ["name", "description", ...] | Controls order and which annotations are printed | | showSourceCode | string[] | ["placeholder", "css", ...] | The documentation types that should display source code | | customAnnotations | function[] | [] | Provide annotation functions (see sassdoc docs for modifying or introducing your own annotations). If you make your own provide a template for output in annotationTemplates | | pageTemplates | object | {} | Provides an object of markdown template functions for any of the page level templates provided by this library (ie. group, section, item). See /lib/templates/page/ for examples. | | annotationTemplates | object | {} | Provides an object of markdown template functions for native sassdoc annotations, custom annotations provided by this library or your own custom annotations. See /lib/templates/annotations/ for examples. | | pageTitleFormatter | function | titleCase | Callback function used to format the page title (from the group name) | | itemTitle | function | (data) => ... | Function to format item titles | | compiler | function | compile | Set custom compiler for sass | | compilerOptions | object | { additionalData: null, ... } | Options passed to sass for compiled sass examples | | sort | function | (a,b) => ... | Callback used to sort (array method) the pages before adding to Vuepress | | outputFiles | boolean | true | Can be used to disable output, ie. using build end to do something manually | | outputTemplate | function | ({ frontmatter, content }) => ... | Template for markdown files | | buildEnd | function | (data) => ... | Callback when page's have been generated/sorted before output | | resolveLink | function | (item, options) => ... | Method to override how links to items are created | | hidePrivate | boolean | false | Whether or not to show items that are flagged with @access private. Will also hide the printout of access in template since all will be public | | hidePrivateKeepGroup | boolean | false | If hiding private, and a private item is the only member of a group this setting will determine if the group is still created. Used for workaround using this to print empty groups (provide info about stylesheets/group which doesn't have mixins/variables/etc [for example if the module just calls a mixin], accomplished by adding private access dummy mixin to scss module so that sassdoc outputs items for the group and enabling this and hidePrivate) |

Changes

Change Log