Documenting Sass variables, mixins and functions

I want to try and document our Sass variables/mixins/functions and wondered if anyone had any suggestions of how to do this? I’ve tried:

1. Documenting them as components, but a component requires a .hbs file. I could create an empty file but then the documentation has a blank component in the preview. Perhaps my config.json file could have a value of preview: false which I could use in the theme to remove the preview - but nobody likes empty files sitting around.
2. Documenting them in the Docs section using .md files. The problem with this is Fractal only allows 1 path to be set for the docs location which means either splitting the documentation from the Sass or creating a task to bundle all documentation into one folder before running Fractal.

I thought about using SassDoc and getting Fractal to <iframe> in the SassDoc export but that seems a little messy.

So, I’m curious to know if anyone has done something similar or could suggest how best to document Sass?

[mikaelkarlsson-se]

Hi! I’ve managed to gather the variables in a specific scss file using a Handlebars helper which uses sass-extract, sass-extract-loader and sass-extract-js to gather and return the variables.

Helper:

const sassExtract = require('sass-extract')  
const createSassExtractJsPlugin = require('sass-extract-js/lib/plugin')  

const sassExtractJsPlugin = createSassExtractJsPlugin({ camelCase: false })  
const scssVariables = sassExtract.renderSync({  
    file: 'path/to/file.scss'  
}, {  
    plugins: [sassExtractJsPlugin]  
})  

fractal.docs.engine(hbs).handlebars.registerHelper('getSassVariables', () => {  
    const variables = []  
    // Note: sass-extract-js returns a object with the keys stats, css and vars and vars is the one needed.  
    Object.entries(scssVariables.vars).forEach(property => {  
        variables.push({  
            variable: property[0],  
            value: property[1]  
        })  
    })  
    return variables  
})  

_index.hbs (my documentation file located in components/docs):

<ul>
    {{#each (getSassVariables)}}
    <li>{{this.variable}} - {{this.value}}</li>
    {{/each}}
</ul>

I hope it can help you. 😃

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.