Getting started

Snippets

So What Are Snippets?

Snippets are reusable 'chunks' of html, css and js that are specific to your documentation. They can be viewed as a type of 'poor mans' component. By design they are simple to use and create. The best way to understand snippets is to write one, so lets get started.

Anatomy of a Snippet

By convention a snippet must have the following structure:

snippets/
   └── my-snippet-name/
       ├── index.js         * contains all JavaScript logic for snippet
       ├── template.html    * the html
       └── style.styl       * snippet css (can be written in stylus format)

By default Swanky will expect to find your snippets in [src]/snippets. You can change this location within your Swanky Configuration file.

Example:

snippets: 'src/some-other-location'

Using Snippets

Snippets are simple to use. Inside of any Markdown__ file you can render a snippet using the following custom _shortcode_ syntax. Using the _square bracket_ notation with the keyword __render tells Swanky to look for a snippet with the following name and provide it with any additional attributes e.g. [render [snippet-name] [attributes]].

Example:

[render colour-drop hex="#2E2E2E" rgb="46 46 46" name="Night Rider"]

Result:

In addition to simply rendering a snippet you can also display the markup__ that was used to generate the snippet. This can be very useful if you need to show the implementation of an element within your documentation. e.g. example button HTML. Using the keyword code in the following __shortcode structure will tell Swanky to render the snippet and to display the HTML in a code block below.

Example:

[code colour-drop hex="#EEEEEE" rgb="238 238 238" name="White Smoke"]

Result:

<div class="colour-drop-wrapper">
  <div class="colour-drop" style="background: #EEEEEE"></div>
  <div class="colour-drop-meta">
    <div class="colour-drop-name">White Smoke</div>
    <div class="colour-drop-code"><strong>RGB</strong> 238 238 238</div>
    <div class="colour-drop-code"><strong>HEX</strong> #EEEEEE</div>
  </div>
</div>

Grouping Snippets

Another useful feature is the ability to group a combination of snippets e.g. form layout. This can easily be achieved using either the render or code keyword followed by -group;

Example:

[code-group]
  [colour-drop hex="#FF5A60" rgb="255 90 96" name="Bittersweet"]
  [colour-drop hex="#43BDD4" rgb="67 189 212" name="Scooter"]
  [colour-drop hex="#FFE11A" rgb="255 225 26" name="Lemon"]
[/code-group]

Result:

<div class="colour-drop-wrapper">
  <div class="colour-drop" style="background: #FF5A60"></div>
  <div class="colour-drop-meta">
    <div class="colour-drop-name">Bittersweet</div>
    <div class="colour-drop-code"><strong>RGB</strong> 255 90 96</div>
    <div class="colour-drop-code"><strong>HEX</strong> #FF5A60</div>
  </div>
</div>


<div class="colour-drop-wrapper">
  <div class="colour-drop" style="background: #43BDD4"></div>
  <div class="colour-drop-meta">
    <div class="colour-drop-name">Scooter</div>
    <div class="colour-drop-code"><strong>RGB</strong> 67 189 212</div>
    <div class="colour-drop-code"><strong>HEX</strong> #43BDD4</div>
  </div>
</div>


<div class="colour-drop-wrapper">
  <div class="colour-drop" style="background: #FFE11A"></div>
  <div class="colour-drop-meta">
    <div class="colour-drop-name">Lemon</div>
    <div class="colour-drop-code"><strong>RGB</strong> 255 225 26</div>
    <div class="colour-drop-code"><strong>HEX</strong> #FFE11A</div>
  </div>
</div>