Getting Started

How to use

The Styleguide is completely modular. This means two things:

  • Content is separated from code
  • Code is split in independent modules

With this in mind, we recommend you to learn how to use the system before moving on to building your project's styleguide.

_data.json files
  • In these files are all the textual content and configurations.
  • There's one in the styleguide folder and one inside each module.
Generated files
  • In the assets/scripts folder a file will be generated if you want to import all of your modules Javascript into your project.
  • In the assets/styles folder a file will be generated if you want to import all of your modules Stylesheet into your project.

Modules

Click here to learn more about modules.

Mac

For Mac users we have an installer with all necessary dependencies to get the Styleguide working.

  • The 'Start' app, will install everything you need. Please check the Known Issues section before running this app. When it's finished the Styleguide will open automaticaly in you browser. If you already have all the dependencies installed in your computer, the Styleguide will open.

  • The 'Compile' app creates a static version of the Styleguide in a 'www' folder.

*Troubleshooting? Click here.

Download for Mac

Windows/Linux

Sorry! We currently don't have any 'magical' app for these platforms. We're working on that.

To use the Styleguide you'll need to execute a couple of commands in the command-line.

*Check the "Manual Install" section.

Download for Windows/Linux

Manual installation

This project has the following dependencies (click to install each of them):

You also need to go to styleguide/structure/_node-files and run:

npm install

To start the Styleguide go to the root folder and execute in the command-line:

harp server
cd styleguide/structure/_node-files && node watch.js

Wait and the browser will open with the Styleguide running.

harp compile

To manually compile the project, go to its root folder and execute (still in the command-line):

cd styleguide/structure/_node-files && node write-date-exec.js
cd ../../.. && harp compile

A folder called 'www' will contain all the compiled files.

Known issues

1 - You should allow unregistered applications to run in order to use the Start.app file. You can do so in Settings > Security & Privacy

2 - The compiled offline version have a smaller issue on Chrome. Chrome have a security policy of not allowing communication with iframes under file:// protocol, so any interaction that needs such communication will be removed (basically the sidebar menu). This is only for the offline compiled version.

3 - If you are a Mac user and after running the Start.app you have this error:

npm ERR! Please try running this command again as root/Administrator.

You have probably installed Node with sudo or root permission. You will need to fix permissions to the .npm folder with the following command:

sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules

After that, try running the Start.app again.

4 - If you have XCode installed but have not agreed with the License you will get this error:

Agreeing to the Xcode/iOS license requires admin privileges, please re-run as root via sudo.

Open XCode and accept the license, then try running Start.app again.

5 - If you get a 404 - No data received error, you might have a port conflict, there are two ways you can change the port number (default to 9241):

  • Change the PORT variable inside styleguide/structure/_node-files/watch.js

  • Set an environment variable (PORT or STYLEGUIDE_PORT):

    If you are running the Styleguide manually, in the last step you might do:

      PORT=7000 node watch.js

    or

      STYLEGUIDE_PORT=7000 node watch.js

    The Start.app is self contained, and for security reasons it does not have access to external variables. If you want to change the port for the Start.app it is recommended to change the watch.js file. You can, if you want, add a variable to your .bashrc file and it will be available for the Start.app:

      touch ~/.bashrc
  echo 'export PORT=1234' >> ~/.bashrc

    or

      echo 'export STYLEGUIDE_PORT=1234' >> ~/.bashrc