Editing the style guide

Please make sure you have read the getting started instructions and installed Middleman to be able to edit the style guide.

Start the middleman server In your terminal navigate to the project folder and run

  $ middleman

You can now edit the files in the source folder and see the changes on your local environment.

Accessing the middleman development server within your network

Depending on the server settings, you should be able to see the source at http://localhost:4567/ or http://0.0.0.0:4567/

To access this domain from another device like a tablet or smartphone, you need to be connected on the same network as the middleman development server. Now find out what your IP address is. The easiest to work with is a fixed IP address.

If your IP address is for example 192.168.0.1 then you can find your site at http://192.168.0.1.xip.io:4567

xip.io is a magic domain name that provides wildcard DNS. xip.io runs a custom DNS server on the public Internet. When your computer looks up a xip.io domain, the xip.io DNS server extracts the IP address from the domain and sends it back in the response.

An introduction to HAML

Our main template language is HAML. You can see haml as a HTML preprocessor, just like SCSS.

What is HAML?

A more concise syntax for coding HTML in your Rails app
Uses indentation for nesting markup
- Reduces code (no closing tags)
- Fixes the messy markup problem that often clutters views
Uses a CSS-like syntax that is easier to read and compare to your style rules
Makes coding your View layer faster
- Note: doesn’t affect render time or client-side performance, simply reduces codingefforts and makes the developer more efficient
Easy to learn!

A comparison

HTML

  <body>
    <div id='wrapper'>
      <div class='stuff'>
        <a href='#'>Top</a>
      </div>
    </div>
  </body>

7 lines, 78 characters

HAML

  %body
    #wrapper
      .stuff
        %a{:href => "#"} Top

4 lines, 36 characters

Read more:

Markdown

For most texts in the styleguide we use the Markdown language. This text is also written in markdown. Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid HTML. HAML is great to create templates, but is not suitable to write long pieces of texts with links and extra markup. In markdown we can easily insert links and format the text.

Markdown is placed inside our HAML files, so we need to give notice where we want to use Markdown. Here is an example:

  %h1#page-title.block-title Markdown
    :markdown
      With hashes we create headings
      # Heading 1
      ### Heading 3

      new paragraphs just need a new line

      we can easily make texts **bold**, _italic_
      and create [links] (http://goto.com).

If you want to learn Markdown quickly you can do this Markdown tutorial.