diff --git a/README.md b/README.md
index 477576f1..207c4a0d 100644
--- a/README.md
+++ b/README.md
@@ -98,6 +98,14 @@ for more info.
Releases
--------
+### 0.5.1: UNRELEASED
+
+- Add optional `show` argument for font-specimen previews —
+ `@preview font-specimen; show: regular, bold, bold italic` —
+ allowing you to override what variants are displayed
+ in the specimen.
+
+
### 0.5.0: 2016-12-09
- Add table output for `@property` annotation,
diff --git a/scss/config/_fonts.scss b/scss/config/_fonts.scss
index 2e163c2d..6154f701 100644
--- a/scss/config/_fonts.scss
+++ b/scss/config/_fonts.scss
@@ -63,7 +63,7 @@ $sans-font: (
// Code Font
// ---------
/// A readable monospace font for code previews.
-/// @preview font-specimen; key: code
+/// @preview font-specimen; key: code; show: regular, bold, bold italic
/// @group webfonts
/// @link http://oddbird.net/accoutrement-type/sassdoc/
/// Accoutrement Type
diff --git a/templates/item/preview.macros.j2 b/templates/item/preview.macros.j2
index 5af2c06c..5b28b441 100644
--- a/templates/item/preview.macros.j2
+++ b/templates/item/preview.macros.j2
@@ -1,6 +1,11 @@
{% import 'utility.macros.j2' as utility %}
+{#
+ Show Previews
+ -------------
+ Call the requested previews with the appropriate JSON data.
+#}
{% macro show_previews(data, name, args) %}
{% if args %}
{% set type = args.type %}
@@ -9,7 +14,7 @@
{% if type == 'color-palette' %}
{{ color_palette(data[key]) }}
{% elif type == 'font-specimen' %}
- {{ font_specimen(key, data[key]) }}
+ {{ font_specimen(key, data[key], args) }}
{% elif type == 'ratios' %}
{{ ratios(data[key], args) }}
{% elif type == 'sizes' %}
@@ -20,6 +25,11 @@
{% endmacro %}
+{#
+ Color Palette
+ -------------
+ Display color palettes based on JSON map output.
+#}
{% macro color_palette(data) %}
{% for name, value in data %}
@@ -42,7 +52,25 @@
{% endmacro %}
-{% macro font_specimen(name, data) %}
+{#
+ Font Specimen
+ -------------
+ Display all font-family specimens,
+ including multiple variants.
+
+ @group font-specimen
+
+ @prop {String} name -
+ Title for the font-family being displayed.
+ @prop {Dict} data -
+ All the available data on a given font,
+ derived from the Sass JSON export.
+ @prop {Dict} args -
+ Arbitrary arguments passes along
+ in the font-specimen call
+ (currently only `show` and `key` are supported).
+#}
+{% macro font_specimen(name, data, args=none) %}
{{ utility.link_if(
@@ -61,44 +89,110 @@
{% endfor %}
- {% set weight_options = [
- '100', '200', '300', '400', '500', '600', '700', '800', '900', 'bold'
- ] %}
- {% set style_options = [
- 'italic', 'oblique'
- ] %}
-
- {% for options, value in data %}
- {% set options = options|split(' ') %}
- {% set variant = options[0] %}
- {% set file = value if (variant in weight_options or variant in style_options or variant == 'regular') else none %}
- {% set weight = 'normal' %}
- {% set style = 'normal' %}
-
- {% for value in options %}
- {% set weight = value if (value in weight_options) else weight %}
- {% set style = value if (value in style_options) else style %}
+ {% set family = [data.name, data.stack]|join(', ') %}
+
+ {% if args.show %}
+ {% for option in args.show|split(', ') %}
+ {{ specimen_variant(
+ family=family,
+ option=option,
+ data=data
+ ) }}
+ {% endfor %}
+ {% else %}
+ {% for option, path in data %}
+ {{ specimen_variant(
+ family=family,
+ option=option,
+ path=path
+ ) }}
{% endfor %}
+ {% endif %}
+
+{% endmacro %}
- {% if file %}
-
-
- {% for option in options %}
- {{ option }}
- {% endfor %}
- ({{ file }}
)
-
-
-
Aa
-
{{ lorem('alpha') }}
-
-
- {% endif %}
+
+{#
+ Specimen Variant
+ ----------------
+ Display a single specimen variant.
+
+ @group font-specimen
+
+ @prop {String} family -
+ A CSS-ready value for font-family,
+ combining both the font name, and fallback font-stack.
+ @prop {String} option -
+ The name of a font variant,
+ e.g. `bold` or `italic` or `700 italic`.
+ @prop {Dict} data [none] -
+ Optional font-data for file-path lookup.
+ @prop {String} path [none] -
+ Optional file-path data,
+ if it is already attached to the option.
+#}
+{% macro specimen_variant(family, option, data=none, path=none) %}
+ {# Local variables for parsing variants in the data #}
+ {% set weight_options = [
+ '100', '200', '300', '400', '500', '600', '700', '800', '900', 'bold'
+ ] %}
+
+ {% set style_options = [
+ 'italic', 'oblique'
+ ] %}
+
+ {% set other_options = [
+ 'normal', 'regular'
+ ] %}
+
+ {# Initialize variants #}
+ {% set weight = 'normal' %}
+ {% set style = 'normal' %}
+
+ {# Split the option into variants, and find files where available #}
+ {% set split_option = option|split(' ') %}
+ {% set variant_check = split_option[0] %}
+ {% set is_variant = true if (variant_check in weight_options or variant_check in style_options or variant_check in other_options) else false %}
+
+ {# If we have an actual variant, display specimen #}
+ {% if is_variant %}
+ {% set path = data.option if data.option else path %}
+
+ {% for value in split_option %}
+ {% set weight = value if (value in weight_options) else weight %}
+ {% set style = value if (value in style_options) else style %}
{% endfor %}
-
+
+
+
+ {{ option }}
+
+ {% if path %}
+ ({{ path }}
)
+ {% endif %}
+
+
+
Aa
+
{{ lorem('alpha') }}
+
+
+ {% endif %}
{% endmacro %}
+{#
+ Lorem
+ -----
+ Display Lorem Ipsum text for font specimens.
+
+ @group font-specimen
+
+ @prop {'title' | 'body' | 'alpha'} length -
+ They type of Lorem Ipsum to display:
+ either title-length, paragraph-length,
+ or a list of standard characters
+ (uppercase, lowercase, numbers, and punctuation).
+#}
{% macro lorem(length) %}
{% if length == 'title' %}