a-pollo

What is a-pollo?

a-pollo is a node module which generates markdown pages decorated with frontMatter data that contains documentation and code snippets supposed to be written in your SASS, LESS or CSS files.

It's meant to be used with a static generator like metalsmith, hexo, jekyll, etc.

Below you'll read a guide on how to configure a-pollo and write annotation tags in order to start building your documentation.

Configuration

The default YAML config is named a-pollo.yml, you should put it on the base directory of your project. Writing your config is easy, here is how it's written:

| Property | Example | Required | Description | | - | - | - | - | | annotations | your/sass/code | true | Where your annotations are, a-pollo expects to find a set of SASS, LESS or CSS files that contains your styles and your annotations | | cache | path/to/cache | false | This is the folder where a-pollo generate the markdown pages decorated with frontMatter data | | front_matter | boolean | false | Decorated generated markdown files with additional metadata useful to static generators | | index | path/to/index.md or boolean | false | Tells to a-pollo to render this markdown page or a path to target your own markdown page | | assets.css | sass/generated/file.css | true | This is the CSS you generate with your source code, a-pollo will style your snippets with it | | assets.fonts | path/to/fonts | false | The fonts loaded from your assets.css | | assets.images | path/to/images | false | The images loaded from your assets.css |

Config example

annotations: './sass'
build: './tmp'
front_matter: true
posts: './path/to/markdown'
index: true
assets:
  css: 'css/example.css'
  fonts: 'css/fonts'
  images: 'css/img'

CLI

The CLI section will be updated soon.

Annotation types

There are four ways to create documentation to your projects, below the list of annotation types:

• Color
• Documentation
• Snippet
• Typography

Color

This annotation expects just one parameter:

| Parameter | Required | Description | | - | - | - | | @a-pollo-color | true | An inline string with che color name you give |

Annotation

Suppose you have a vars.scss file, you can add color annotation in this way:

$color-azure: #135aa3; /* @a-pollo-color: Azure */

The annotation needs to be inline with the var or it will not work.

Generated frontMatter

annotations:
  -
    annotation: "color"
    category: "identity"
    name: "Azure"
    path:
      root: "/"
      base: "vars.scss"
      ext: ".scss"
      name: "vars"
      relative: "sass/frontsize/themes/_config"
      project: "/samples/sass/frontsize/themes/_config"
    type: "color"
    title: "Color"
    var: "$color-azure"
    value: "#135aa3"
    names:
      basic: "indigo"
      html: "darkslateblue"
      ntc: "Azure"
      pantone: "Denim"
      roygbiv: "indigo"
      x11: "darkslateblue"
    css:
      rgb: "rgb(19, 90, 163)"
      hsl: "hsl(210, 79%, 36%)"
      hex: "#135AA3"
      cmyk: "cmyk(88%, 45%, 0%, 36%)"
    channel:
      cmyk:
        c: 88
        m: 45
        y: 0
        k: 36
      hsl:
        h: 210
        s: 79
        l: 36
      rgb:
        r: 19
        g: 90
        b: 163

Documentation

This annotation parameters:

| Parameter | Required | Description | | - | - | - | | @a-pollo-doc | true | The annotation tag | | @author | | Inline markdown string | | @category | | Inline string | | @code | | Inline markdown string as first parameter, multiline code block as second parameter | | @css | | Inline markdown string as first parameter, multiline code block as second parameter | | @date | | A valid date | | @html | | Inline markdown string as first parameter, multiline code block as second parameter | | @icon | | Inline string, meant to be used to store a CSS class selector | | @name | true | Inline string | | @param | | First parameter expects an inline string with {typeof} data, ($var-name) and if your parameter is [required], the second parameter is an inline markdown string | | @public | | If you shoud use the entity as public | | @returns | | If this code block returns something | | @text | | Multiline markdown string | | @title | | Inline string | | @type | | A string to define the type of entity you are working with | | @version | | If your code is used from a specific release |

Annotation

The @code tag will be colored by the extension of it's source code, if you write it in a SASS file, the code will be colored as SASS code.

/*
  @a-pollo-doc
  @author: [Vittorio Vittori](http://vit.to)
  @title: BEM
  @category: Components
  @code: Example on using the mixin with some static property
    @include block (button) {
      background: #3f6c44;
      color: #fff;
      display: inline-block;
      font-size: 12px;
      padding: 4px 8px;
    }
  @css: This is the CSS generated
    .button {
      background: #3f6c44;
      color: #fff;
      display: inline-block;
      font-size: 12px;
      padding: 4px 8px;
    }
  @date: 2016-12-28T17:40:42+01:00
  @type: mixin
  @html: A simple HTML element to see how mixin works
    <a class="button" href="#">Visit this link</a>
  @icon: fa fa-css3
  @name: block
  @param: {string} ($block-name) [required]
          Defines the block name of the BEM component
  @public: true
  @returns: css
  @text: Defines the block name of the BEM component. This mixin is required as wrapper of `element` and `modifier` mixins
  @version: 4.0.0
*/

This annotation is meant if you need to write code documentation, if you just need to write code snippets, go the ne snippet annotation.

Generated frontMatter

annotations:
  -
    annotation: "doc"
    author: "<p>Vittorio Vittori</p>\n"
    category: "Components"
    date: "2016-12-28T17:40:42+01:00"
    html:
      code: "<a class=\"button\" href=\"#\">Visit this link</a>"
      copy: "<a class=\"button\" href=\"#\">Visit this link</a>"
      snippet: "<pre><code class=\"lang-html\">&lt;a class=&quot;button&quot; href=&quot;#&quot;&gt;Visit this link&lt;/a&gt;\n</code></pre>\n"
      source: "<a class=\"button\" href=\"#\">Visit this link</a>"
      text: "<p>A simple HTML element to see how mixin works</p>\n"
    icon: "fa fa-css3"
    name: "block"
    params:
      -
        default: "required"
        name: "$block-name"
        text: "<p>Defines the block name of the BEM component</p>\n"
        type: "string"
    path:
      root: "/"
      base: "bem.scss"
      ext: ".scss"
      name: "bem"
      relative: "sass/frontsize/core/components"
      project: "/samples/sass/frontsize/core/components"
    public: true
    returns: "css"
    text: "<p>Defines the block name of the BEM component. This mixin is required as wrapper of <code>element</code> and <code>modifier</code> mixins</p>\n"
    type: "mixin"
    version: "4.0.0"
    title: "BEM"
    code:
      ext: "scss"
      code: "@include block (button) {\n  background: #3f6c44;\n  color: #fff;\n  display: inline-block;\n  font-size: 12px;\n  padding: 4px 8px;\n}"
      snippet: "<pre><code class=\"lang-scss\">@include block (button) {\n  background: #3f6c44;\n  color: #fff;\n  display: inline-block;\n  font-size: 12px;\n  padding: 4px 8px;\n}\n</code></pre>\n"
      text: "<p>Example on using the mixin with some static property</p>\n"
    css:
      code: ".button {\n  background: #3f6c44;\n  color: #fff;\n  display: inline-block;\n  font-size: 12px;\n  padding: 4px 8px;\n}"
      snippet: "<pre><code class=\"lang-css\">.button {\n  background: #3f6c44;\n  color: #fff;\n  display: inline-block;\n  font-size: 12px;\n  padding: 4px 8px;\n}\n</code></pre>\n"
      text: "<p>This is the CSS generated</p>\n"

Snippet

This annotation parameters:

| Parameter | Required | Description | | - | - | - | | @a-pollo-snippet | true | The annotation tag | | @author | | Inline markdown string | | @category | | Inline string | | @date | | A valid date | | @html | | Inline markdown string as first parameter, multiline code block as second parameter | | @icon | | Inline string, meant to be used to store a CSS class selector | | @name | true | Inline string | | @text | | Multiline markdown string | | @title | | Inline string |

/*
  @a-pollo-snippet
  @name: button-social
  @author: [Vittorio Vittori](http://vit.to)
  @date: 2017-01-06T17:50:18+01:00
  @category: Buttons
  @icon: fa fa-hand-pointer-o
  @text: The base usage without styles of the button, this component **requires** [FontAwesome](http://fontawesome.github.io) to be loaded as dependency.
  @html:
    <a href="#" class="button-social" data-style="width: 150px;">
      <div class="button-social__icon">
        <i class="fa fa-dashboard"></i>
      </div>
      <div class="button-social__network">
        Button
      </div>
    </a>
*/

Note

Inside the @html tag you can add the attribute data-style, this will be converted as inline stile for display examples, but will be not copied in the clipboard.

Typography

This annotation parameters:

| Parameter | Required | Description | | - | - | - | | @a-pollo-typography | true | The annotation tag | | @name | | Inline string | | @selector | | CSS selector to render the typography in the documentation | | @text | | Multiline markdown string | | @usage | | Inline string |

Annotation

The @selector tag will be colored by the extension of it's source code, if you write it in a SASS file, the code will be colored as SASS code.

/*
  @a-pollo-typography
  @name: Merriweather
  @usage: paragraph
  @selector: .text.text--big
  @text: This is used for paragraphs text blocks, it's nice on web browser and digial devices with low or high density displays.
        If you need to write on physical object it's recommended to use [Kepler STD](https://typekit.com/fonts/kepler).
*/

Generated frontMatter

annotations:
  -
    annotation: "typography"
    category: "identity"
    name: "Merriweather"
    path:
      root: "/"
      base: "text.scss"
      ext: ".scss"
      name: "text"
      relative: "sass/fonts/widgets"
      project: "/samples/sass/fonts/widgets"
    text: "<p>This is used for paragraphs text blocks, it&#39;s nice on web browser and digial devices with low or high density displays.\n If you need to write on physical object it&#39;s recommended to use <a href=\"https://typekit.com/fonts/kepler\">Kepler STD</a>.</p>\n"
    usage: "paragraph"
    type: "snippet"
    title: "Typography"
    alphabet:
      uppercase: "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
      lowercase: "abcdefghijklmnopqrstuvwxyz"
      symbols: "‘?’“!”(%)[#]{@}/&<-+÷×=>®©$€£¥¢:;,.*"
    selector: ".text.text--big"
    selectorClass: "text text--big"
    preview:
      title: "Suec ebraaj baj sef buvzocpi ke"
      sentence: "No ofifizel worewu voectu deuduh iw awicioh lutu"
      paragraph: "Hejobtap upepa jukvedlu vof atleh lej kodaer luvuhtun ebapuha az jinu ri tah jusoror. Disazse ciniug naduco wectormof uj cog poczo kanuju numijev ivel piz vozuj bihsol ciamudit okrezaf ohoaj cuhpuk. Wusguek kabfi agete gibnahsiv vegebewo ciged ul ge guthor ga favu razle ev jotricez luw. Funcorjid nod zuc da zo pu pefam sapfiso fo satgi hotbaho debic. Tacev zam ona tufuap nihoopa dadvafaw la wu az fohpah keagu fuvu kamone hu gotohu. Wir lapoz wetceme sonjo ku mos athage hafvivpo weh fudol ogiti vodite idimuhir kup fe. Tivsipmi lo fu um eru mehcuni kisno wufugdo hawihe pu hog ja petugko zipur ivo. Ehlazo esegepam so cevipag farivogeb ko nub buwabut sa jokomlit mabwuf tovoge fiv. Ic emmokkoj ojoove za esowihih bacdig bov gih jib osbij barigku amuva numvepug lu ziebe losev orsugjeh. Na av jawduobo labopmaf zi vohgim wi joz deenzot cagun gocuwene dihake razcatkat ijajod wajhuces gic. Av feb iheuwiwi jovek couju ri tarpa okahe ufbu kafwa jumoc osewil ne ganvumjok tacnuljon."