Seldon NPM | npm.io

seldon

Nodejs CSS documentation generator inspired by hologram.

This is a work in progress. This project currently works as a simple node script, but don't expect unicorns and rainbows (yet).

1. Use structured comments in your CSS

/*doc

title: My Component Title name: myUniqueComponentName

category: My Category Name

Any markdown you want can go here. Github-flavored markdown supported.

&lt;p&gt;This is a special fenced code block that does neat things:&lt;p&gt;
&lt;ol&gt;
	&lt;li&gt;Put example code here&lt;li&gt;
	&lt;li&gt;It will be rendered directly to static documentation&lt;li&gt;
	&lt;li&gt;Escaped html will appear under the example&lt;li&gt;
&lt;ol&gt;

2. Create a Seldon config file

config.json

{
	"source": "../sq2/sass/",
	"destination": "build/index.html",
	"assets": [
		"templates/static/"
	],
	"templates": {
		"layout": "templates/layout.hbs",
		"example": "templates/example.hbs"
	}
}

Property	Description
`source`	any dir containing files with structured comments
`destination`	target dir for built docs (will be created if it doesn't exist)
`assets`	static assets you'd like to copy into the `destination` dir (files will be copied to the root of `destination`)
`templates["layout"]`	main handlebars template
`templates["example"]`	template used to render `html_example` blocks

Running Seldon

$ npm install seldon --save-dev

Use as a node module

const Seldon = require('seldon');

Seldon.compile('./config.json');

Use from the command line

$ node seldon.js /path/to/config/config.json

3. Seldon creates a view for handlebars

{
	myCategory: {
		title: "My Category",
		name: myCategory,
		blocks: [ //components filed under this category
			{
				title: "My Component Title",
				name: "myUniqueComponentName",
				description: "(html string compiled from markdown, including html_example blocks)"
			},
			{
				title: "My Other Component in this category",
				name: "myOtherComponent",
				description: "(html string compiled from markdown, including html_example blocks)",
				children: [ /* nesting is supported with the `parent` convention from hologram docs */
					{
						title: "My child component",
						name: "childComponent",
						description: "(html string compiled from markdown, including html_example blocks)",
					}
				]
			}
		]
	}
}