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.
- In these files are all the textual content and configurations.
- There's one in the styleguide folder and one inside each module.
- In the assets/styles folder a file will be generated if you want to import all of your modules Stylesheet into your project.
Click here to learn more about modules.
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
This project has the following dependencies (click to install each of them):
You also need to go to styleguide/structure/_node-files and run:
To start the Styleguide go to the root folder and execute in the command-line:
cd styleguide/structure/_node-files && node watch.js
Wait and the browser will open with the Styleguide running.
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.
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
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
echo 'export STYLEGUIDE_PORT=1234' >> ~/.bashrc