The heart of creating a.
.gif)
Yourself from the future after reading the docs you wrote in the past.
Tutorial Part 3
In this part of the tutorial we will be documenting stylesheets in a living style guide and learn:
- How to add documentation to an existing stylesheet
- How to organize documentation
- How to break down style documentation into sensible chunks
- How to create sections in the living style guide
We will be using for this tutorial a sample application. For installation instructions check the previous tutorial part.
Documenting a Stylesheet
Documenting a stylesheet follows a similar pattern to documenting a page, but in this case the documentation will go inside of a comment, right next to the code (that’s the beauty!).
To get started open the stylesheet:
buttons-custom.less .
Inside of this file, and inside of a comment block, add the tag
@stylesheet followed by two strings:
/** @stylesheet buttons.less Buttons */
Note that a such in the style guide. This serves to differentiate it from other types of documents, like pages, components, and models, among others (read here about the full list of document types). will be:
Buttons
Similar to creating a page, this is the title of the stylesheet that will be used for display purposes in the generated site. Here you can use multiple words with spaces or other characters.
To view the newly created page run the following command unless you have it watching for changes):
documentjs
And then go to to view the new page.
Now, let's add this new doc to our navigation. For this we will follow the same convention we used when we created the page by using the
@parent tag:
/** * @stylesheet buttons.less Buttons * @parent styles.base */
Note that in this case we have added
.base to specify this page should appear under the group "Baseline" shown in the sidebar (you can also create groups in your subnav! We will dig into that in a little bit).
Re-running the docs and refreshing the page 😎
Let’s add a quick description and a demo for our buttons doc:
/** * @stylesheet buttons.less Buttons * @parent styles.base * @description * Global style definitions for all button elements. * @iframe src/base/bootstrap-custom/buttons/buttons-custom.html */
Rerun the docs, and 🎉:
As you can see the
@iframe tag allows to add an iframe it. Like this:
/** * @stylesheet buttons.less Buttons * @parent styles.base * * @description * Global style definitions for all button elements. * @demo src/base/bootstrap-custom/buttons/buttons-custom.html */
Which will output like this:
Demos credit goes to Bootstrap Docs where we snap the code from.
Now, before you go bananas with this, there are a couple of more goodies that you can take advantage of:
- Creating Style Sections
- Creating Stylesheet Groups
Creating Style Sections
To create a style section you can use the tag
@styles. This tag is sweet because it allows you to break down your stylesheet doc into sensible chunks that you can talk about and understand better.
For instance, in our example, we have styles for defining buttons in general, regardless of the markup that is used ( either a
<button/> vs
<a/> tag). And then we have definitions of color. With the
@styles tag we can break the color definitions into their own section, not only to talk about them separately, but to be able to hyperlink to that section directly.
This is how it works. In the same file
buttons-custom.less, we are going to add the tag
@styles right after the first block of styles and before the color variables. Here's how it should look like:
/** * @stylesheet buttons.less Buttons * @parent styles.base * * @description * Global style definitions for all button elements. * @demo src/base/bootstrap-custom/buttons/buttons-types.html */ .btn { display: inline-block; ...} /** * @styles buttons-colors Button Colors * * @description * Buttons can be displayed in the following colors: * @demo src/base/bootstrap-custom/buttons/buttons-color.html */ @btn-default-color: #333;
- I updated the first demo to show only the button types.
- I added a new comment block using the
@stylestag. Here I gave it a unique name
button-colorsand the title of
Button Colors. I also gave it a
@descriptionand added a
@demofor it that only shows the button colors.
And here’s the output:
Notice that the new comment block is now a section within the "Buttons" doc, which you can also access directly using this url:
I personally find this super useful because you can point people to a specific section in the style guide, vs saying: "is in x page, under x section, then you need to scroll...and blah, blah, blah". Instead you can provide a direct link to it, and end of the story.
Creating Stylesheet Groups
Additionally, you can also create sections or groups in the sidebar of the style guide. For this, open the file
styles.md, located in the
markdown directory.
You will notice here a new tag called
@group.
@page styles Styles @group styles.theme 0 Theme @group styles.base 1 Baseline The styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.
Now let’s break down the second line:
@group
The
@group tag allows you to create a section in the sidebar that appears under the parent section. For example, the groups: "Theme" and "Baseline" will appear under the parent section of "Styles".
styles.theme
This is the unique name for the group. A good practice to follow here is to use the name of the parent section, in this case "Styles" as a namespace. In this way, if you want to create another group with the same name, but under a different section, the name of the group will remain unique.
0
This is the order in which the group should appear, which starts with 0. If no order is assigned, then the list of groups will be shown in alphabetical order.
Theme
This is the actual name that will show in the sidebar, so you can use multiple words with spaces and other characters.
To see groups in action, let’s add a new group as follows:
@page styles Styles @group styles.theme 0 Theme @group styles.base 1 Baseline @group styles.forms 2 Forms The styles shown in this section show how elements are styles with definitions from the Bootstrap framework, in addition to any customizations made for this specific project. Therefore they will be available for use in any part of the application.
Finally, let’s add an existing doc under this new section. For this open the file
forms-custom.less:
And on line 3, replace
styles.base for
styles.forms.
/** * @stylesheet forms-custom.less Form Elements * @parent styles.forms **/
Then run the docs and refresh the browser. You will now see the "Form Elements" doc under the group "Forms" in the sidebar.
Wrap Up
Living Style Guides are a tool to create more consistent and cohesive UI designs, and you can really take advantage of them when applying the Style Guide Driven Development Approach and when designing in a Modular Way.
You, building living style guides at this point!
At this point, if you have been following along you should now have a running Living Style Guide, and a well thought-out plan to create a LSG that you can use as a baseline for other projects. But if you haven’t be sure to check Part 1 (Planning Your Living Style Guide) and Part 2 (Creating a Basic Page).