Styledoc is a set of tools and conventions for easy style authoring and documentation. It is based around some of these technologies and language definitions:

Asciidoctor Bundler Node.js Pug Ruby Sass

License:

Introduction

HTML and CSS is still the simplest way to build and design a static website. This is due to the fact graphical web editors for HTML and CSS are never WYSIWYG, instead they’re mostly WYSIWYM - what you see is what you mean. But the best way to write HTML/CSS isn’t foregoing of writing it but using the right tools for the job and abstracting away the complexity in the right way. When we augmenting our workflow to use of Pug/Sass, seemingly unmanagable projects can become managable. The overhead to those tools is minimal and at the same time we get wonders of improved productivity and reusability of components.

Sass is a de facto standard for working with CSS. Pug (aka jade) is an awesome indentation based abstraction markup for working with HTML. These two tools toghether with Asciidoctor provide a powerfull basis for building our Documentation driven Website.

💬
Styledoc methodology allows you to create and document your websites with ease. Documentation is generated with Asciidoctor from files that have .ad or .adoc extension and parts of the code is included with Passtrough declaration with the help of Pug includes.

All the necessary steps for a complete Styledoc workflow might not be have been described yet. Please help to improve it on github.com/styledoc/styledoc. You can also assist in the creation of the Stylez boilerplate github.com/styledoc/stylez - that is based on npm scripts.

Stylez boilerplate for Styledoc

Stylez

Stylez boilerplate www.npmjs.com/package/stylez provides npm scripts that can help you get started building your site with Pug and Sass and document it with the help of Asciidoctor.

Here is how the typical Styledoc project is layed out:

.
├── asciidoctor
│   ├── asciidoctor-extension-bash-dollar.js
│   ├── asciidoctor-extension-mdn.js
│   └── main.css
├── build
│   └── build.js
├── css
│   ├── asciidoctor.css
│   ├── coderay-asciidoctor.css
│   ├── index.ad.css
│   ├── maps
│   │   ├── asciidoctor.css.map
│   │   ├── index.ad.css.map
│   │   └── stylez.css.map
│   ├── stylez.css
│   └── stylez.css.map
├── _footer.html
├── gulpfile.js
├── _header.html
├── img
│   └── stylez.svg
├── index.adoc
├── index.html
├── LICENSE
├── package.json
├── package-lock.json
├── _pug
│   ├── _footer.pug
│   ├── _header.pug
│   ├── index.pug
│   └── test
│       ├── _footer.pug
│       ├── _header.pug
│       └── index.pug
├── README.md
├── _sass
│   ├── asciidoctor.scss
│   ├── index.ad.scss
│   └── stylez.scss
├── s_component1
│   └── index.adoc
├── s_component2
│   └── index.adoc
├── s_component3
│   └── index.adoc
├── server.js
├── styledoc
│   ├── Gemfile
│   ├── index.ad
│   ├── index.html
│   ├── _index.style.html
│   ├── _index.style.pug
│   ├── Makefile
│   ├── s_component1
│   │   └── index.html
│   ├── s_component2
│   │   └── index.html
│   ├── s_component3
│   │   └── index.html
│   ├── style.bat
│   ├── test.ad
│   ├── _test.style.html
│   └── _test.style.pug
└── test
    ├── _footer.html
    ├── _header.html
    ├── index.html
💡
In case you only need to publish documention from your Sass file comments you may find sassdoc.com easier to work with. For pure styleguide generators there are github.com/kneath/kss or github.com/kss-node/kss-node and livingstyleguide.org. If you are looking for JavaDoc-like styleguide commenting tool with the same name, there is: github.com/thybzi/styledoc

Learn more about Pug and Sass here:

both are the tools that you could use via Node.js.

Advantages to modular markup are plentifull, there is a great blog post if you need some introduction: explosion.ai/blog/modular-markup. Not only is it the structure of HTML that is augmented and simplified with Pug, it also allows you move and indent the order of code blocks with keyboard shortcuts of your code editor.

To get started with Node.js, choose LTS version and install it. Navigate to your project directory and run npm install.

It is recomended that you use Git for your projects version control: git-scm.com/book/en/v2/Getting-Started-About-Version-Control.

The starting points

The starting points of each Styledoc project is index.html (a regular index page for your website) which is generated from _pug/index.pug and index.adoc (a file at the root of directory) that gets converted to styledoc/index.html which serves as the base of your documentation.

Windows users

On Windows there is an option Git for Windows option gitforwindows.org. Make sure to check the box for Git Bash when you install it (during "Select Components" section). Don’t forget to also check the box for Bash scripts if want to run those. After installation the easiest way to run the terminal emulation is to have the access to it in your code editor or IDE. Most modern editors have added support for it. In VS Code you get in via View menu and selecting Integrated Terminal and choosing Git Bash. Since most of the Web and the Internet runs on Linux and Unix, having ability to use shell scripts for Web development is important. Also Npm scripts often use POSIX/UNIX standards to do their work. Git Bash already has plenty of utilities but you could also easily add your own. For example on Windows you could use ripgrep instead of the usual grep tool, just add it to /mingw64/bin/rg of your "Git for Windows" directory. To get good overview of your project files there is TortoiseGit which makes it incredibly easy for Git newcomers. For more full featured but simplified graphical interface there is www.sourcetreeapp.com/, it is just one of many git-scm.com/downloads/guis available so choose the ones you are most comfortable with.

Styledoc Git repository

If you want to look at how Styledoc documentation is written and you use Git, just clone the repository

git clone https://github.com/styledoc/styledoc.git

otherwise you could also download a zip file from github.com/styledoc/styledoc

and install it

npm install

CSS and scss

Some CSS resources to get you started with CSS:

In recent years Sass has become a defacto standard for working with CSS. StyleDoc recommendation is to use .scss files, those are more similar to the regular .css files and are friendlier for newcomers to Sass to understand.

If you previously used Ruby version, consider switching to high performant version written in C (LibSass). Here you can find out moreabout Sass compatibility between LibSass and Ruby version. Styledoc uses www.npmjs.com/package/sass that is pure Javascript based on the Dart implementation, the build is handled via Gulp pipeline with the help of www.npmjs.com/package/gulp-dart-sass

If you need to concatenate your css files, consider using something like concat with this npm script example:

"build:concat": "concat -o dist/css/styles.css dist/css/style.css assets/css/test.css",

CSS och Sass (.scss files) should be modular, don’t use id or !important and try to get rid of unnecessary nesting in CSS/Sass. Use separate classes for your styles so that they can be reusable and make it easier to reason about and work together. Prolifiration of class names isn’t something to be afraid of and working with them becomes a second nature when you use Pug. Pug and Sass will help you to keep your code DRY! Sass Parent selector and some pseudoclasses are the only "nestnig" in Sass where it is defendable to use this method.

Consult CSS Guidlines for ways of working with SCSS/CSS.

To convert your CSS to SCSS there is a Node.js package npm install -g css-scss-cli.

To see how to use it, consult css-scss --help. If you wish to have nicer looking scss files there are plenty of Beautify SCSS and Sass Linter plugins for most modern editors.

Sass Parent selector

Sass Parent selector is an awesome feature that allows you to set relatable classes together in one block. This method makes it easier to maintain your styles and reuse the components without worrying about breaking CSS specificity.

There is a good animation that conceptually describes how Sass parent selector works: codepen.io/richfinelli/pen/qbZgQK.

NPM scripts and workflow automation

NB! Some npm scripts need to be installed globally, use -g flag to install them. One such script is pug-cli, although the script is still in development stage it’s very usefull to generate html files in places not defined by Styledoc configuration.

The file package.json contains a list over npm scripts in use, the tasks are divided into two groups: build and watch. Watch tasks run the build command first and then monitor file changes to process your assets automatically.

The script npm-run-all bundles and runs those tasks together in parallel. Build and watch conventions are probably the most used ones with npm scripts and are easy to wrap your head around how they work. For post prefixes and other features, read the official documentation NPM scripts.

Watch scripts rebuilds adoc, pug and sass files. It is the watch:adoc script starts a simple local web server to preview your pages at 127.0.0.1:3000 and builds index.adoc files at the root level of the project and in directories that begion with s_. It doesn’t automatically autoupdate pages on change, that keeps things simple but also means that you might consider using a browser plugin to refresh your pages periodically. To run it separately, use this command:

npm run watch:adoc

otherwise it will start when you run watch script group

npm run watch

Press Ctrl C if you would like to exit the scripts.

HTML and Pug

HTML is a markup language that lacks strictness, therefore itis extremely forgiving if you write it with errors. The problem is then that you are no longer in control of how your pages will be rendered, the browser that runs it will arbitrarily decide how it’s done.

Pug (aka jade) is a strict abstraction that helps you create good HTML documents (or even XML).

In order to idiot proof HTML, HEAD and BODY tags the Styledoc convention is to encode those three as regular html-tags. See Conventions and methods on how it is achieved.

Pug has indentation based syntax (you would be familiar to you if you used languages like Python). Therefore it is important to use a code editor that would help you with indentation based workflow. You might consider installing a better indentation plugin than the standard one that comes with your editor. Examples being indent-guide-improved for Atom and indent-rainbow for VS Code, but there are many more for all types of text editors.

Conventions and methods

The core philosophy behind Styledoc is that it should be a modular way to build and document your stylesheets. Sass is the major style building tool, in order to make it familial to newcomers scss file format should be used. Pug is one of the best ways to generate parts of HTML code, which is why it’s used.

Directories that begin with underscore contain intermediate files that are abstracting away some of the complexity in web pages and help with reusability. Files that begin with underscore are partials, those ought to be imported into other files to produce the final results.

HTML, HEAD and BODY tags should be used as literal html angle bracket tags in Pug documents in order to keep that structure more robust and less prone to risk of having a "headless body" HTML file in your outputs. It could look like this:

doctype html
<html lang="en">
  <head>

then write head content as a regular Pug and end it with html tag and begin the body tag:

  </head>
  <body>

write the body in Pug style and then close your body and html tags:

  </body>
  </html>

at the bottom of your document.

You can extend templates with Pug. To see how this works check teplate.pug and test.pug that extends it. It can help you structure parts of the website and have similar styling for related pages.

Asciidoctor.js based documentation

Files that get converted with Asciidoctor.js reside in directories that begin with s_. For example s_component1 has one index.adoc file that is the base for describing some specific parts of the website.

When those index files are converted the output is placed in the styledoc directory.

Asciidoctor (Ruby) based documentation

The regular documentation based on the Asciidoctor Ruby resides in styledoc and needs the help from Bundler and Makefile or bat-file (Batch script) to be converted.

Documenting with style

Style documents are intermediate files that reside in styledoc directory and have .style.pug and .style.html file endings.

Files with .style.pug endings is a trick that simply tells us to include the generated html into our style documentation. When Pug file is converted into html, those 4 plus signs become necessary to invoke Asciidoctor Passthrough and include the partial pug file into our rendered html format. Example of _test.style.pug file could be something like this:

| ++++
|
include ../_pug/_test.pug
|
| ++++

Include statement goes on level up in file directory and includes _test.pug from _pug directory.

To generate the corresponding html file - just run:

pug _test.style.pug

It gets converted into html code with .style.html file ending (i.e _test.style.html) and 4 plus signs at the top and bottom of each document ( to be used for for Asciidoctor Passthrough in .ad file).

Example for the contents of such _test.style.html file would be:

++++
<h2>Hello world!</h2>
++++

It means that _test.pug from _pug would have looked like:

h2
  Hello world!

The .style. suffix is used to denote that those files are used for style documentation.

Asciidoctor and Bundler

The standard Asciidoctor toolchain is written in Ruby.

On Windows the easiest way to get going with Ruby programming language is to use Ruby installer.

In order to work on your Styledoc files you would need Bundler. To install it run:

gem install bundler

Then install the Ruby gems

bundle install

If you don’t have a Gemfile, you can initialize it within your styledoc directory with bundle commando:

bundle init

It will create Gemfile with a list of dependencies and their versions.

to add Asciidoctor to your Styledoc project run:

bundle add asciidoctor

to add Coderay source highlighting, run:

bundle add coderay

When you include .style.html files in your .ad files in a styledoc project you would also need to have the corresponding css files in your final output if you want to create styleguide like document.

On Windows, create style.bat in your styledoc derectory - a batch script that can process your .ad asciidoctor files and add appropriate css to them:

@ECHO OFF
for %%F in (./*.ad) do (
        bundle exec asciidoctor -a stylesdir=../css ./%%F -a linkcss -a stylesheet=%%F.css
)

In a first row you can see that this script runs in a silent mode, %%F is a filename descriptor (.ad files). The third line is the instruction to run Asciidoctor via bundler (bundle exec).

Use .ad file ending as a way to separate Styledoc related files from other Asciidoctor documents such as .asciidoc and .adoc.

🚨
Do not begin to name your .ad files with underscore if you are using Sass as it will not convert the styles for such files (those are considered partials which .ad files are not).

In order to write style documents for partials begin their name with inc_ meaning that you are describing a file that is included or is a partial of a bigger file. Let’s say we have a partial file _header.html made from _header.pug We could either call our ad file for it html-header.ad and only document the html part. Otherwise we call it inc_header.ad and document both _header.html and _header.pug in tandem within the same .ad file.

The other way to run the same script is to use Makefile (install Git for Windows and check the Bash box during install). Batch skript style.bat as well as Makefile script both link to CSS files with the same name (i.e .ad.css files) . Therefore you would need to make sure that the corresponding files with .ad.scss file endings exist in your _sass directory (relative to the root directory and not styledoc folder).

It would then result in .ad.css files being produced in css directory. With Sass in order to attach the css to your style document (example.ad) create the corresponding example.ad.scss with import statement:

@import "example.scss";

To get Asciidoctor css in your final files add asciidoctor.scss to the second line:

@import "example.scss"
@import "asciidoctor.scss";

This ability to produce the living style guide kind of documents can be limited by the styles and classes defined in asciidoctor.scss and asciidoctor.css. Check that those are compatible, otherwise you would need to define your cutom styling for asciidoctor main html elements and import that instead

@import "example.scss"
@import "asciidoctor-custom.scss";

On Linux/Mac/UNIX systems you should use Makefile that looks like this:

all: style
style:
	ls *.ad | xargs -n1 -I{} bundle exec asciidoctor -a stylesdir=../css {} -a linkcss -a stylesheet=../css/{}.css

.PHONY: all

Ls command lists all files with .ad file endings and then pipes it to asciidoctor rutine where xargs puts the correct file name arguments in place.

If you wish to use multiple cores, xargs has this simple flag for you: for example -P4 would use 4 processor cores.

all: style
style:
	ls *.ad | xargs -n1 -P4 -I{} bundle exec asciidoctor -a stylesdir=../css {} -a linkcss -a stylesheet=../css/{}.css

.PHONY: all

You will end up with html file (example.html) that has this style embedded:

<link rel="stylesheet" href="../css/example.ad.css">

Sass ignores scss files that begin with underscore so make sure to start naming your .ad files with a letter or a number.

For partial files that begin with underscore, depending on how you decide to document those it would look something like this:

  • pug-example.ad

  • html-example.ad

  • inc-example.ad - let’s say if your style document describes small example.pug and example.html partials - all in one .ad file.

So for inc-example.ad.scss you would have

@import "example.scss"
@import "asciidoctor.scss";

If you use Git for Windows you can run Make from Bash command line

Each Styledoc document for Sass (.ad files) should begin by describing variables. In your Sass .scss file put some tag comments (e.g vars) around it:

// tag::vars[]
$lightblue: #1b98f8;
$darkgrey: #333;
// end::vars[]

You decide on what tag will be called ( in this case vars) , just don’t forget to close it with end declaration. It allows you to include the part between the tag comments in your Styledoc .ad file like so:

include::../_sass/test.scss[tag=vars]

To get the correct formatting you put this between the lines of source declaration:

[source,sass]
----

include::../_sass/test.scss[tag=vars]

----

Now you have this code in the document and you are ready to comment on it!

Node.js and npm scripts

Install Node.js.

In your project directory:

npm install

this will install script dependencies.

to start watch subroutine on npm:

npm run watch

Npm scripts are specified in package.json (this command will run all ascripts that beging with watch:). When it’s running you can modify your .pug and .scss files and it will create .html and .css automatically.

SVG icons and other graphics

To optimize images in _svg directory and _pug/_svg (for inline inline svg icons in html):

npm run svgo

It creates web optimized wersions of your files in svg directory, as well as in _pug/svg for inline icons.

If your project has alot of icons it can be a good idea to introduce some script that can handle svg sprites.

When SVG files are added inline with Pug include they should reside within _pug/svg directory.

The benefits to using Pug include is that the placement of your SVG files becomes easy to change without cluttering your Pug documents.

Let’s say we have some icons that get added into _pug/svg directory. With include this is very easy to add to your Pug document:

  include ./svg/example.svg
⚠️
notice that the syntax for include in Pug and Asciidoctor is similar but different!

To decide the dimensions of our SVG, we open it in code editor and change width and height to suit our needs:

<svg xmlns="http://www.w3.org/2000/svg" width="120" height="120"

Here is a blog post about using your SVG icons inline: Pretty good SVG icon system.

Documenting with Asciidoctor

Asciidoctor allows you to tag parts of your code like this:

// tag::hello[]
hello world!
// end::hello[]

For comments, use // in both Pug and Sass:

// some comment...

it allows you to deside if it will end up in .ad documents that contain and show parts of the code.

// some comment that will not end up in .ad-file (styledoc document)
// tag::hello[]
hello world!
// end::hello[]

by moving the comment after the // tag:: line will render it in the final html output of .ad-file (example.ad gets converted to example.html)

To include HTML or Pug code parts, use include statement in Asciidoctor. See Asciidoctor user manual for more.

Asciidoctor source highlighting with Coderay

In order to have your source code highlighted you first need to gem install coderay in your styledoc directory.

To get it to work add it somewhere after the first title in your .ad file.

= Example title
:source-highlighter: coderay

When Makefile or Batchscript converts the .ad files into html it will include the coderay css along with your style specific .ad.css file in the final html output:

<link rel="stylesheet" href="../css/example.ad.css">
<link rel="stylesheet" href="../css/coderay-asciidoctor.css">

In your Gemfile, in styledoc folder should have coderay listed, if it doesn’t - in styledoc directory run:

bundle add coderay