👾 Styledoc is a set of tools and conventions for easy style authoring and documentation writing. It is based around Asciidoctor.js, Pug, Sass and Node.js scripts. If you want to use Asciidoctor (Ruby) - put those files in styledoc folder and run Makefile or Batch scripts in order to process them with the help of Bundler.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_pug
_sass
asciidoctor
build
css
img
s_component1
s_component2
s_component3
styledoc
test
.gitignore
CHANGELOG.adoc
CONTRIBUTING.adoc
LICENSE
Q&A.md
README.adoc
_footer.html
_header.html
gulpfile.js
index.adoc
index.html
intro.adoc
package-lock.json
package.json
server.js
tree.txt

README.adoc

Styledoc

styledoc

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.

Premise

Even for the relatively simple static web sites one can sprinkle some comments to HTML and CSS. But this is not documentation and it’s generally not enough, also terse writing is not always easy (to write or to read). As we add more comments, our code becomes overshadowed so we no longer are able to find the things we’re looking for at a glance. It is important to understand that comments and docs are not the same and should serve different purposes. Documentation doesn’t have to be just the description of your styles. It might just as well work as a specification and a set of common goals and rules that your team follows. Although Styledoc can be used to make a Living-styleguide there should be better tools for that, especially if you are creating Javascript heavy Web apps.

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.

The workflow is automated with npm scripts for Pug/Sass and Makefile (or Batch script on Windows) for Asciidoctor .ad files - allowing you to create a simple living styleguide like documents. Styledoc values reusability and decoupled nature of its components. If you don’t like one part of the process you can simply edit package.json or gulpfile.js and remove or change the processes without having to be a Javascript guru.

Style

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!
— Zen of Python

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.

Tools

Some tools that Styledoc is based on:

Pug

PUG adresses some major pittfall of HTML - it makes it easier to write, easier to update and most importantly - it allows reusable content.

Asciidoctor

Asciidoctor - arguably the best text based tools to write documentation for multiple purposes.

Sass

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.