Add asides for nice-looking notes and warnings

You can now use <aside> with the classes - warning - success - notice to add little colored notes to your API docs! Examples are in source/index.md. Also, note that if you have a custom variables.scss, you'll have to add +$aside-notice-bg: #8fbcd4; +$aside-warning-bg: #c97a7e; +$aside-success-bg: #6ac174; to it.
2026-01-12 22:44:57 +08:00 · 2013-10-31 12:26:07 -07:00
parent ca40fed573
commit d3ab3cc4b7
10 changed files with 128 additions and 5 deletions
--- a/README.md
+++ b/README.md
@@ -184,4 +184,5 @@ Special Thanks
 - [Middleman](https://github.com/middleman/middleman)
 - [jquery.tocify.js](https://github.com/gfranko/jquery.tocify.js)
 - [middleman-syntax](https://github.com/middleman/middleman-syntax)
- [middleman-gh-pages](https://github.com/neo/middleman-gh-pages)
+- [middleman-gh-pages](https://github.com/neo/middleman-gh-pages)
+- [Font Awesome](http://fortawesome.github.io/Font-Awesome/)
--- a/config.rb
+++ b/config.rb
@@ -4,6 +4,8 @@ set :js_dir, 'javascripts'

 set :images_dir, 'images'

+set :fonts_dir, 'fonts'
+
 set :markdown_engine, :redcarpet

 set :markdown, :fenced_code_blocks => true, :smartypants => true, :disable_indented_code_blocks => true, :prettify => true, :tables => true, :with_toc_data => true, :no_intra_emphasis => true
--- a/source/fonts/icomoon.eot
+++ b/source/fonts/icomoon.eot
--- a/source/fonts/icomoon.svg
+++ b/source/fonts/icomoon.svg
@@ -0,0 +1,17 @@
+<?xml version="1.0" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" >
+<svg xmlns="http://www.w3.org/2000/svg">
+<metadata>Generated by IcoMoon</metadata>
+<defs>
+<font id="icomoon" horiz-adv-x="1024">
+<font-face units-per-em="1024" ascent="960" descent="-64" />
+<missing-glyph horiz-adv-x="1024" />
+<glyph unicode="&#x20;" d="" horiz-adv-x="512" />
+<glyph unicode="&#xe600;" d="M438.857 950.857q119.429 0 220.286-58.857t159.714-159.714 58.857-220.286-58.857-220.286-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857zM512 238.286v108.571q0 8-5.143 13.429t-12.571 5.429h-109.714q-7.429 0-13.143-5.714t-5.714-13.143v-108.571q0-7.429 5.714-13.143t13.143-5.714h109.714q7.429 0 12.571 5.429t5.143 13.429zM510.857 434.857l10.286 354.857q0 6.857-5.714 10.286-5.714 4.571-13.714 4.571h-125.714q-8 0-13.714-4.571-5.714-3.429-5.714-10.286l9.714-354.857q0-5.714 5.714-10t13.714-4.286h105.714q8 0 13.429 4.286t6 10z" horiz-adv-x="878" />
+<glyph unicode="&#xe601;" d="M512 237.714v109.714q0 8-5.143 13.143t-13.143 5.143h-109.714q-8 0-13.143-5.143t-5.143-13.143v-109.714q0-8 5.143-13.143t13.143-5.143h109.714q8 0 13.143 5.143t5.143 13.143zM658.286 621.714q0 50.286-31.714 93.143t-79.143 66.286-97.143 23.429q-138.857 0-212-121.714-8.571-13.714 4.571-24l75.429-57.143q4-3.429 10.857-3.429 9.143 0 14.286 6.857 30.286 38.857 49.143 52.571 19.429 13.714 49.143 13.714 27.429 0 48.857-14.857t21.429-33.714q0-21.714-11.429-34.857t-38.857-25.714q-36-16-66-49.429t-30-71.714v-20.571q0-8 5.143-13.143t13.143-5.143h109.714q8 0 13.143 5.143t5.143 13.143q0 10.857 12.286 28.286t31.143 28.286q18.286 10.286 28 16.286t26.286 20 25.429 27.429 16 34.571 7.143 46.286zM877.714 512q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" horiz-adv-x="878" />
+<glyph unicode="&#xe602;" d="M585.143 237.714v91.429q0 8-5.143 13.143t-13.143 5.143h-54.857v292.571q0 8-5.143 13.143t-13.143 5.143h-182.857q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h54.857v-182.857h-54.857q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h256q8 0 13.143 5.143t5.143 13.143zM512 749.714v91.429q0 8-5.143 13.143t-13.143 5.143h-109.714q-8 0-13.143-5.143t-5.143-13.143v-91.429q0-8 5.143-13.143t13.143-5.143h109.714q8 0 13.143 5.143t5.143 13.143zM877.714 512q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" horiz-adv-x="878" />
+<glyph unicode="&#xe603;" d="M656.571 382.857q0 14.857-10.857 25.714l-103.429 103.429 103.429 103.429q10.857 10.857 10.857 25.714 0 15.429-10.857 26.286l-51.429 51.429q-10.857 10.857-26.286 10.857-14.857 0-25.714-10.857l-103.429-103.429-103.429 103.429q-10.857 10.857-25.714 10.857-15.429 0-26.286-10.857l-51.429-51.429q-10.857-10.857-10.857-26.286 0-14.857 10.857-25.714l103.429-103.429-103.429-103.429q-10.857-10.857-10.857-25.714 0-15.429 10.857-26.286l51.429-51.429q10.857-10.857 26.286-10.857 14.857 0 25.714 10.857l103.429 103.429 103.429-103.429q10.857-10.857 25.714-10.857 15.429 0 26.286 10.857l51.429 51.429q10.857 10.857 10.857 26.286zM877.714 512q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" horiz-adv-x="878" />
+<glyph unicode="&#xe604;" d="M694.857 475.429v73.143q0 14.857-10.857 25.714t-25.714 10.857h-146.286v146.286q0 14.857-10.857 25.714t-25.714 10.857h-73.143q-14.857 0-25.714-10.857t-10.857-25.714v-146.286h-146.286q-14.857 0-25.714-10.857t-10.857-25.714v-73.143q0-14.857 10.857-25.714t25.714-10.857h146.286v-146.286q0-14.857 10.857-25.714t25.714-10.857h73.143q14.857 0 25.714 10.857t10.857 25.714v146.286h146.286q14.857 0 25.714 10.857t10.857 25.714zM877.714 512q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" horiz-adv-x="878" />
+<glyph unicode="&#xe605;" d="M694.857 475.429v73.143q0 14.857-10.857 25.714t-25.714 10.857h-438.857q-14.857 0-25.714-10.857t-10.857-25.714v-73.143q0-14.857 10.857-25.714t25.714-10.857h438.857q14.857 0 25.714 10.857t10.857 25.714zM877.714 512q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" horiz-adv-x="878" />
+<glyph unicode="&#xe606;" d="M733.714 604.571q0 16-10.286 26.286l-52 51.429q-10.857 10.857-25.714 10.857t-25.714-10.857l-233.143-232.571-129.143 129.143q-10.857 10.857-25.714 10.857t-25.714-10.857l-52-51.429q-10.286-10.286-10.286-26.286 0-15.429 10.286-25.714l206.857-206.857q10.857-10.857 25.714-10.857 15.429 0 26.286 10.857l310.286 310.286q10.286 10.286 10.286 25.714zM877.714 512q0-119.429-58.857-220.286t-159.714-159.714-220.286-58.857-220.286 58.857-159.714 159.714-58.857 220.286 58.857 220.286 159.714 159.714 220.286 58.857 220.286-58.857 159.714-159.714 58.857-220.286z" horiz-adv-x="878" />
+</font></defs></svg>
--- a/source/fonts/icomoon.ttf
+++ b/source/fonts/icomoon.ttf
--- a/source/fonts/icomoon.woff
+++ b/source/fonts/icomoon.woff
--- a/source/index.md
+++ b/source/index.md
@@ -49,7 +49,9 @@ Kittn expects for the API key to be included in all API requests to the server i

 `Authorization: meowmeowmeow`

-You must replace `meowmeowmeow` with your personal API key from our developer portal.
+<aside class="notice">
+You must replace `meowmeowmeow` with your personal API key.
+</aside>

 # Kittens

@@ -108,6 +110,9 @@ Parameter | Default | Description
 include_cats | false | If set to true, the result will also include cats.
 available | true | If set to false, the result will include kittens that have already been adopted.

+<aside class="success">
+Remember — a happy kitten is an authenticated kitten!
+</aside>

 ## Get a Specific Kitten

@@ -144,6 +149,8 @@ curl "http://example.com/api/kittens/3"

 This endpoint retrieves a specific kitten.

+<aside class="warning">If you're not using an administrator API key, note that some kittens will return 403 Forbidden if they are hidden for admins only.</aside>
+
 ### HTTP Request

 `GET http://example.com/kittens/<ID>`
@@ -158,6 +165,7 @@ ID | The ID of the cat to retrieve

 The Kittn API uses the following error codes:

+
 Error Code | Meaning
 ---------- | -------
 400 | Bad Request -- Your request sucks
--- a/source/stylesheets/icon-font.scss
+++ b/source/stylesheets/icon-font.scss
@@ -0,0 +1,49 @@
+@font-face {
+  font-family: 'icomoon';
+  src:font-url('icomoon.eot');
+  src:font-url('icomoon.eot?#iefix') format('embedded-opentype'),
+    font-url('icomoon.ttf') format('truetype'),
+    font-url('icomoon.woff') format('woff'),
+    font-url('icomoon.svg#icomoon') format('svg');
+  font-weight: normal;
+  font-style: normal;
+}
+
+%icon {
+  font-family: 'icomoon';
+  speak: none;
+  font-style: normal;
+  font-weight: normal;
+  font-variant: normal;
+  text-transform: none;
+  line-height: 1;
+}
+
+%icon-exclamation-sign {
+  @extend %icon;
+  content: "\e600";
+}
+%icon-question-sign {
+  @extend %icon;
+  content: "\e601";
+}
+%icon-info-sign {
+  @extend %icon;
+  content: "\e602";
+}
+%icon-remove-sign {
+  @extend %icon;
+  content: "\e603";
+}
+%icon-plus-sign {
+  @extend %icon;
+  content: "\e604";
+}
+%icon-minus-sign {
+  @extend %icon;
+  content: "\e605";
+}
+%icon-ok-sign {
+  @extend %icon;
+  content: "\e606";
+}
--- a/source/stylesheets/screen.css.scss
+++ b/source/stylesheets/screen.css.scss
@@ -3,6 +3,7 @@
@import 'compass';
@import 'variables';
@import 'syntax';
+@import 'icon-font';

 /*
 Copyright 2008-2013 Concur Technologies, Inc.
@@ -29,6 +30,7 @@ html, body {
  padding: 0;
  margin: 0;
  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
  @extend %default-font;
  background-color: $main-bg;
 }
@@ -212,10 +214,8 @@ html, body {
  z-index: 30;


-  &>h1, &>h2, &>h3, &>p, &>table, &>ul, &>ol {
+  &>h1, &>h2, &>h3, &>p, &>table, &>ul, &>ol, &>aside {
    margin-right: $examples-width;
-  }
-  &>h1, &>h2, &>h3, &>p, &>table, &>ul, &>ol {
    padding: 0 $main-padding;
    @include box-sizing(border-box);
    display: block;
@@ -330,6 +330,49 @@ html, body {
    @extend %break-words;
    @extend %code-font;
  }
+
+  aside {
+    padding-top: 1em;
+    padding-bottom: 1em;
+    text-shadow: 0 1px 0 lighten($aside-notice-bg, 15%);
+    margin-top: 1.5em;
+    margin-bottom: 1.5em;
+    background: $aside-notice-bg;
+    line-height: 1.6;
+
+    &.warning {
+      background-color: $aside-warning-bg;
+      text-shadow: 0 1px 0 lighten($aside-warning-bg, 15%);
+    }
+
+    &.success {
+      background-color: $aside-success-bg;
+      text-shadow: 0 1px 0 lighten($aside-success-bg, 15%);
+    }
+  }
+
+
+  aside.warning {
+  }
+
+  aside:before {
+    vertical-align: middle;
+    padding-right: 0.5em;
+    font-size: 14px;
+  }
+
+  aside.notice:before {
+    @extend %icon-info-sign;
+  }
+
+  aside.warning:before {
+    @extend %icon-exclamation-sign;
+  }
+
+  aside.success:before {
+    @extend %icon-ok-sign;
+  }
+
 }


--- a/source/stylesheets/variables.scss
+++ b/source/stylesheets/variables.scss
@@ -34,6 +34,9 @@ $lang-select-bg: #222;
 $lang-select-active-bg: $examples-bg; // feel free to change this to blue or something
 $lang-select-pressed-bg: #111; // color of language tab bg when mouse is pressed
 $main-bg: #eaf2f6;
+$aside-notice-bg: #8fbcd4;
+$aside-warning-bg: #c97a7e;
+$aside-success-bg: #6ac174;


 // TEXT COLORS