While the bulk of your LSG documentation will come from special comments that you add to the source code, you can also create standalone pages where you can host other types of content that are not specific to the code (think of design principles, accessibility guidelines, or pull request guidelines). This gives you the advantage of centralizing your documentation in one place: your application living style guide.
Tutorial Part 2
In this part of the tutorial we will be creating standalong pages in a living style guide and:
- Installing a sample application that uses DoneJS and DocumentCSS
- Creating a simple page
- Adding the page to the living style guide navigation
- Adding content to the page
For additional context on the subject to living style guides and to learn how to plan your own be sure to check the part one of this tutorial.
You could almost think of the living style guide as the “game rules” of your app. Inside of “the rules” is all the information that is needed on how to “play” the game: The building blocks and the rules for creating and making building new blocks. Including how other members of your team can contribute to it and help maintaining it as a living document.
With this in mind, let's get started by installing the sample application that we will use for this tutorial.
Installing the Sample Application
The installation process has 3 steps:
1. Installing Node
First, make sure you have Node installed. You will need at least version 6.
2. Installing the App
Download this zip file: lsg-docss.zip to your Desktop and unzip it. This is important as another location would break the install commands.
Note that this script is for mac users. If you are a windows user, you can reference the commands that are used in the Appendix, at the end of this post.
Then open the terminal and enter the following command:
cd ~/Desktop/lsg-docss && sudo ./install.sh
You will be prompted to enter your system password. Enter it and then the installation will begin.
3. Running the App
Once the installation is done you will see 3 steps to follow in the terminal. Follow those steps to run the server and the docs and 🎉.
Now, let’s break this down:
If you are familiar with command line you will know that all that we are doing here is changing to another directory, in this case
vintage-shop. We do this because this is the directory that contains the app source code.
Starts a server where you can see your app running at: http://localhost:8080. You will see in the terminal:
And in the browser:
Generates the living style guide at http://localhost:8080/styleguide. You can add the flag
-w to this command to watch for changes in your code and then generate an update in the living style guide. Switching to the browser you should see:
The generated living style guide uses DocumentCSS, so let's take a look at how does this work.
How does DocumentCSS Work?
DocumentCSS is a static site generator. This means it looks for specially formatted comments in your code and creates a static website. This site is called “static” because it remains unchanged until a command (in this case documentjs) is run again. This workflow works well for generating a living style guide as changes to your stylesheets are also changes to the Living Style Guide static site.
To build a living style guide, DocumentCSS does the following:
- Reads through files specified in its configuration (for this tutorial it will be looking at
- Looks for comments that uses special “tags” (like
- Generates html files and connects them to build the site.
With this in mind let’s jump into using DocumentCSS to create a new page in the LSG.
Creating a Page
To begin, first open the sample application in your code editor. You should see the following file structure:
Drill down into src , and find
base/markdown. Here you will find pages that already exist in the style guide. Create a new markdown file and name it “about” (with the extension
.md). Your file structure should now look like this:
Inside of this new file, add the tag
@page followed by two strings:
@page about about
Now let's break this down:
This is the unique name for the page and is used as a reference to other tags. So keep it short, lowercase and simple as it will be used as the url for the page. For our example, the url for our new page will be: http://localhost:8080/styleguide/about.html
This is the title of the page that will be used for display purposes in the generated site. Here you can use multiple words with spaces or other characters.
The next step is to add your page to the navigation. For this add a second line to your file as follows:
@page about About
@parent allows to specify a parent for your document. In this case we want the "About" page to show under the home section. Now, you can rerun the docs and see the page appear below the “Welcome” link:
And if you click on the "Welcome" link, you can access the start page:
Now we are good to add content to this page using markdown or html. To finish the exercise, let’s add the following dummy content:
@page about About @parent index ## Hello World! This is the first page of my style guide. Here I can add any type of content that shouldn’t live with the code. Like who are the main contributors of the style guide or contact info. For example here's an animated gif inside of an `iframe`: <iframe class="giphy-embed" src="https://giphy.com/embed/3o7TKMt1VVNkHV2PaE" width="480" height="480" frameborder="0" allowfullscreen="allowfullscreen"></iframe>
And here’s the output:
Now that you know how to create a basic page in the living style guide, you can move on to learning how to document a stylesheet. The principles will be the same but with additional features.
Here are the commands used in the installation script:
npm install donejs -g
|installs the app framework|
npm install documentjs -g
|installs the documentation engine|
|switches to the project root|