Styledoc is a set of tools and conventions for easy style authoring and documentation writing. It is opinionated, utilizes a few loosely coupled components and promotes reusability.
Many thanks to Thomas Parisot for his excellent work on Nodebook - a book about Node.js (in French), without which this project might not have been possible! Styledoc uses some of the code for build scripts from nodebook repository.
This project is still evolving and needs help, particularly in the realm of documentation and stylesheet designs. Everyone is encouraged to contribute! If you have concerns about the code, please file an issue.
Discuss on gitter chat.
Styledoc values modularity and simplicity. Design of web pages is a laborious process, the choises of the tools that are available can sometimes be overwhelming. For most projects it is a big collaborative effort, where being on the equal footing with you colleagues and adhering to the same principles and methods is important for productivity. Sass of one such tool, another one is Node and npm. With Styledoc the core principle is separation of concerns, writing HTML is abstracted by Pug. For documentation Styledoc uses one of the best tools available: Asciidoctor.
Styledoc is not a static site generator, nor is it an automatic styleguide making tool. Instead it embraces the concept of Documention Driven Development and provides the methodology for the websites that use Sass/Pug to document their styles with Asciidoctor toolchain.
Sass is used with scss file format to make it more familiar to newcomers that have used CSS but haven’t used Sass. Apply the CSS best practices to keep specificity as low as possible! It means: don’t use nested classes and don’t use id’s or !important.
Ideas for naming of Sass scss components
Two letter prefixes for namespacing.
Namespaces are one honking great idea - let’s do more of those!
Source control versioning in style documentation
Choose the tool of your liking: Git or Mercurial or whatever else that you like. However, SemVer versioning and Git source control are recomended as those are more widespread.
If you are using Git with multiple repositories and need a more advanced tool, take a look at Antora which also uses Asciidoc markup for documentation and is based on Asciidoctor.js.
Compared to other methods and tools
Unlike KSS, SassDoc or some other style documentation methods, using Asciidoctor with Styledoc will keep your documentation separate. You can tag your classes using a simple comment syntax and include only the needed part in your documention. There is no imperative requirement on how you should write your documentation. As such it can also be used as a specification tool before the design work has even been completed.
Some tools that Styledoc is based on:
PUG adresses some major pittfall of HTML - it makes it easier to write, easier to update and most importantly - it allows reusable content.
Asciidoctor - arguably the best text based tools to write documentation for multiple purposes.
Sass and it’s scss syntax is simple enough to be picked up by even a novice to CSS world, at the same time it allows us to use some powerfull features to ease the complexity of working with stylesheets.
Npm Node package manager cross platform way to work with web technologies on your system.