@ulu/sassdoc-to-markdown

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
  • Compiled Sassdoc Example
  • Preview HTML Example
• Configuration
• Changes

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