--- layout : 'default' css : 'guide' title : 'Local Docs' description : 'A guide to generating docs locally' type : 'Semantic Project' --- <%- @partial('header') %>

Step by Step

It may be useful to run the development docs locally when working on a forked version of semantic, as the docs themselves help in testing out changes to ui components.

1. Install Node

Semantic docs are written in DocPad which requires NodeJS.

Make sure npm does not require sudo to operate, this might cause permissions issues.

There are many tutorials online on how to install node in your environment, here are a few we think are helpful:

2. Fork Semantic

Fork the Semantic repo into a directory on your local machine and navigate into that directory

Alternatively, you can download the entire repository as a zip instead of using Git

3. Install Dependencies

NPM (Node Package Manager) keeps track of all the dependencies required for the project.

Updating npm inside the local directory will grab all development dependencies from package.json and store them in the root of the project.

npm update; npm install;

4a Creating Packages for Server

Additionally your server needs to have the latest version of Semantic built before the documentation will appear formatted correctly. Running grunt build will create a version of the library at docs/build available for your server

grunt build

4b Watching Files

Docpad will automatically generate a static (html/css only) version of the documentation everytime you update a file inside server/

If you would like it to build semantic everytime you edit a file inside src/ you will have to run the grunt watch script.

grunt watch;

4c. Start Your Server

Now that you've installed all the dependencies, starting your server should be a simple command

docpad run

Docpad should now run the documentation on a local server accessible at http://localhost:9778

A static version of the documentation will be generated every time you make a change to a document. This will also be available in the docs/ folder.

5. (Optional) Install Karma

Unit tests are written in Jasmine, but are run using a test runner called Karma. To install karma you need to grab the npm package.

npm install -g karma

Installing Karma will allow you to run the unit tests on Javascript to ensure all tests are passed when changes are made to javascript code. This will also occur automatically when you create a pull request

Using Grunt

Watch Changes in Source

If you are working on fixing a UI component that is part of Semantic, your best bet is to work actively on the file in /src/{type}/{elementname}/ while running a watch script from grunt. This will rebuild the docs after you make changes, so you can see if you have corrected the issue you are fixing.

To see exactly what this grunt tasks is doing view our commented gruntfile

grunt

The watch task is the default grunt task for Semantic, so you can start it quite simply. This will copy files automatically from the src directory, compiling LESS files, whenever any changes are made.

Run Unit Tests

Tests will automatically run with grunt watch if you have started karma

karma start grunt watch

You can also run the test suite manually

npm test // or grunt test // or karma run

Build Semantic Packages Locally

There is also a separate grunt command for building minified, packaged, and compressed versions of the library. This might be useful when creating custom builds of Semantic.

grunt build

Next: Library Introduction