Skip to content

Commit 8972e6e

Browse files
author
Ryan A. Johnson
committed
refactor(docs): refactor Nunjucks templates
* move `lorem()` macro to `docs/_templates/_utils.njk` * move `disclosure()` macro to `docs/components/modals/test.html` (the only place it's used) * refactor `docs/_templates/application.njk` to handle all layout configuration logic * refactor `component.njk`, `element.njk`, `guide.njk`, and `test.njk` according to refactor of `application.njk` * remove several unnecessary partials (added directly in `application.njk`) * added "View Source" link to global header (next to "Report Bug") * migrated all application of CSS padding to `docs.less` instead of explicit `hxBox` classes in layout so as to simplify changes needed to modify styling in the future. * update `min-version.njk` to remove "else" logic (all components and elements should have a minimum version defined). The `<min-ver>` element will not be shown if missing from frontmatter configuration. * add sticky warning banner and test page styling to communicate that no example from ANY test page should be replicated by consumers * fixed extra padding on the horizontal layout preview * refactor layout previews to extend `application.njk` instead of redefining their own nunjucks layout * move breadcrumbs to page header in vertial layout preview * refactored home page `docs/index.html` to take advantage of new layout configurations and to correct semantic markup of content
1 parent 1804e15 commit 8972e6e

24 files changed

+433
-515
lines changed

‎docs/_templates/_utils.njk‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,24 @@
77
{{element(elementName)}}
88
</a>
99
{% endmacro %}
10+
11+
{% macro lorem(n=1) %}
12+
{% for i in range(0, n) -%}
13+
<p>
14+
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
15+
tempor incididunt ut labore et dolore magna aliqua. Gravida rutrum quisque
16+
non tellus. Sagittis vitae et leo duis ut diam quam nulla. Diam vel quam
17+
elementum pulvinar etiam non. Pulvinar sapien et ligula ullamcorper
18+
malesuada proin libero nunc. Ultricies integer quis auctor elit sed
19+
vulputate mi sit amet. Egestas dui id ornare arcu odio ut. In iaculis nunc
20+
sed augue. Pellentesque adipiscing commodo elit at imperdiet dui accumsan
21+
sit amet. Erat velit scelerisque in dictum non. Auctor augue mauris augue
22+
neque gravida in fermentum et. Posuere sollicitudin aliquam ultrices
23+
sagittis orci a scelerisque purus. Ullamcorper dignissim cras tincidunt
24+
lobortis feugiat vivamus at augue. Tincidunt vitae semper quis lectus
25+
nulla. Purus ut faucibus pulvinar elementum integer enim neque volutpat.
26+
Etiam sit amet nisl purus in mollis nunc. Diam sit amet nisl suscipit.
27+
Nulla pharetra diam sit amet nisl. Arcu odio ut sem nulla.
28+
</p>
29+
{%- endfor %}
30+
{% endmacro %}

‎docs/_templates/application.njk‎

Lines changed: 137 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,169 @@
11
<!DOCTYPE html>
22
<html lang="{{site.language}}">
33
<head>
4-
{% include 'partials/head.njk' %}
4+
<title>{% if page.title %}{{page.title}} - {% endif %}{{site.title}}</title>
5+
<meta charset="utf-8">
6+
<meta name="viewport" content="width=device-width, initial-scale=1">
7+
<base href="{{site.baseHref}}">
58

6-
{% block head %}
7-
{# custom stuff goes here #}
8-
{% endblock %}
9+
<link rel="shortcut icon" href="images/favicon.png">
10+
11+
{# Font Awesome Brand Icons #}
12+
<link
13+
crossorigin="anonymous"
14+
href="https://use.fontawesome.com/releases/v5.2.0/css/brands.css"
15+
integrity="sha384-nT8r1Kzllf71iZl81CdFzObMsaLOhqBU1JD2+XoAALbdtWaXDOlWOZTR4v1ktjPE"
16+
rel="stylesheet"
17+
/>
18+
{# Font Awesome Core Styles (required for Brand icons) #}
19+
<link
20+
crossorigin="anonymous"
21+
href="https://use.fontawesome.com/releases/v5.2.0/css/fontawesome.css"
22+
integrity="sha384-HbmWTHay9psM8qyzEKPc8odH4DsOuzdejtnr+OFtDmOcIVnhgReQ4GZBH7uwcjf6"
23+
rel="stylesheet"
24+
/>
25+
26+
{# HelixUI Styles (generated from src/) #}
27+
<link rel="stylesheet" href="dist/styles/helix-ui.css">
28+
{# Documentation Styles (generated from docs/) #}
29+
<link rel="stylesheet" href="docs.css">
30+
31+
<!-- Converts ES5 custom element constructor functions to ES6 classes -->
32+
<script src="vendor/custom-elements-es5-adapter.js"></script>
33+
34+
<!-- loader appends polyfills, if needed -->
35+
<script src="vendor/webcomponents-loader.js"></script>
936
</head>
10-
<body class="hxVertical" id="top">
37+
<body class="{{bodyClass | d('hxVertical')}}" id="top">
1138
<!-- This link should be the first item a user can tab to. -->
1239
<a href="#content">Skip to main content</a>
1340

1441
<header id="head">
15-
{% include 'partials/global_nav.njk' %}
42+
<nav>
43+
<a class="brand-logo" href="">
44+
<img src="images/helix-logo.svg" alt="Logo" />
45+
</a>
46+
</nav>
47+
48+
<div>
49+
<a
50+
class="hxBtn beta-hxDark"
51+
href="https://github.com/rackerlabs/helix-ui/"
52+
>
53+
<i class="fab fa-github"></i>
54+
<span>View Source</span>
55+
</a>
56+
<a
57+
class="hxBtn beta-hxDark"
58+
href="https://github.com/rackerlabs/helix-ui/issues/new?template=bug-report.md&labels=Bug:+Unconfirmed"
59+
>
60+
Report Bug
61+
</a>
62+
</div>
1663
</header>
1764

1865
<div id="app">
1966
<div id="stage">
2067
<nav id="nav" class="hxNav">
21-
{% include 'partials/app_nav.njk' %}
68+
{% block app_nav %}
69+
{% include 'partials/app_nav.njk' %}
70+
{% endblock %}
2271
</nav>
2372

24-
{% block layout %}
25-
<main role="main" id="content">
73+
<main role="main" id="content" class="{{mainClass}} {{contentClasses}}">
74+
{% block main %}
75+
<header>
76+
{# TODO: use frontmatter to define breadcrumbs #}
77+
{% block breadcrumbs %}
78+
{# breadcrumbs go here (optional) #}
79+
{% endblock %}
80+
81+
<h1>
82+
{{ page.title }}
83+
84+
{% if page.minver %}
85+
{% include 'partials/min-version.njk' %}
86+
{% endif %}
87+
</h1>
88+
89+
{% if page.beta %}
90+
{# TODO: convert to official Banner when available in HelixUI assets #}
91+
<hx-alert type="warning" status="BETA" persist>
92+
Not recommended for production use.
93+
</hx-alert>
94+
{% endif %}
95+
96+
{% block page_header %}
97+
{# extra header content goes here #}
98+
{% endblock %}
99+
</header>
100+
26101
{% block content %}
27102
{# page content goes here #}
28103
{% endblock %}
29-
</main>
104+
{% endblock %}
105+
106+
{% if page.also %}
107+
{% include 'partials/see-also.njk' %}
108+
{% endif %}
109+
</main>
30110

111+
{% if hasSiderail %}
31112
<aside class="hxSiderail">
32-
{% block sidebar %}
33-
{% include 'partials/sidebar.njk' %}
113+
{% block siderail %}
114+
<header>
115+
<h1 class="hxHeading-4">On this page:</h1>
116+
</header>
117+
118+
<nav class="article-toc">
119+
{{ page.raw | toc | safe }}
120+
{% block toc %}
121+
{# extra links go here #}
122+
{% endblock %}
123+
{% if page.also %}
124+
<a href="#see-also">See Also</a>
125+
{% endif %}
126+
<hr class="hxDivider" />
127+
<a class="top-link" href="#top">Back to Top</a>
128+
</nav>
34129
{% endblock %}
35130
</aside>
36-
{% endblock %}
131+
{% endif %}
37132
</div>
38133
</div>
39134

40135
<footer id="foot" class="hxRow hxGutterless">
41-
{% include 'partials/footer_nav.njk' %}
136+
<div class="hxCol">
137+
&copy; 2019 Rackspace US, Inc.
138+
<nav>
139+
<a href="https://www.rackspace.com/information/legal/websiteterms">Website Terms</a>
140+
<a href="https://www.rackspace.com/information/legal/privacystatement">Privacy Policy</a>
141+
</nav>
142+
</div>
143+
144+
<div class="hxCol hxRight">
145+
{% if page.updated %}
146+
<small>
147+
Last Updated:
148+
{{ page.updated.format(site.dateFormat) }}
149+
</small>
150+
{% endif %}
151+
152+
<small>
153+
(<a href="https://github.com/rackerlabs/helix-ui/releases/v{{VERSION}}" target="_blank">
154+
v{{VERSION}}
155+
</a>)
156+
</small>
157+
</div>
42158
</footer>
43159

44-
{% include 'partials/after_footer.njk' %}
160+
{# Documentation Dependencies #}
45161

46-
{% block after_footer %}
47-
{# custom scripts/markup go here #}
48-
{% endblock %}
162+
{# Vue for Interactive Demos #}
163+
<script src="https://unpkg.com/[email protected]/dist/vue.js"></script>
164+
{# HelixUI Behavior (generated from src/) #}
165+
<script src="dist/scripts/helix-ui.browser.js"></script>
166+
{# Documentation Behavior (generated from docs/) #}
167+
<script src="docs.js"></script>
49168
</body>
50169
</html>

‎docs/_templates/component.njk‎

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,3 @@
11
{% extends 'application.njk' %}
2-
3-
{% block layout %}
4-
<main id="content" class="component-content {{contentClasses}}">
5-
<header>
6-
{% block breadcrumbs %}
7-
{# breadcrumbs go here (optional) #}
8-
{% endblock %}
9-
10-
<h1>
11-
{{ page.title }}
12-
{% include 'partials/min-version.njk' %}
13-
</h1>
14-
15-
{% if page.beta %}
16-
<hx-alert type="warning" status="BETA" persist>
17-
This component is not recommended for production use.
18-
</hx-alert>
19-
{% endif %}
20-
21-
{% block page_header %}
22-
{# extra header content goes here #}
23-
{% endblock %}
24-
</header>
25-
26-
{% block content %}
27-
{# freeform page content goes here #}
28-
{% endblock %}
29-
30-
{% if page.also %}
31-
{% include 'partials/see-also.njk' %}
32-
{% endif %}
33-
</main>
34-
<aside class="hxSiderail">
35-
{% include 'partials/sidebar.njk' %}
36-
</aside>
37-
{% endblock %}
2+
{% set hasSiderail = true %}
3+
{% set mainClass = 'component-content' %}

‎docs/_templates/element.njk‎

Lines changed: 36 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -1,81 +1,48 @@
11
{% extends 'application.njk' %}
2+
{% set hasSiderail = true %}
3+
{% set mainClass = 'element-content' %}
24

3-
{% block layout %}
4-
<main id="content" class="element-content">
5-
<header>
6-
{% block breadcrumbs %}
7-
{# breadcrumbs go here (optional) #}
8-
{% endblock %}
5+
{% block toc %}
6+
<a href="#attributes">Attributes</a>
7+
<a href="#properties">Properties</a>
8+
{% endblock %}
99

10-
<h1>
11-
{{ page.title }}
12-
{% include 'partials/min-version.njk' %}
13-
</h1>
10+
{% block main %}
11+
{{super()}}
1412

15-
{% block page_header %}
16-
{# extra header content goes here #}
17-
{% endblock %}
13+
{# ATTRIBUTES #}
14+
<section>
15+
<header>
16+
<h2 id="attributes">Attributes</h2>
17+
<p>
18+
Attributes enable declarative configuration of an element,
19+
via HTML markup.
20+
</p>
1821
</header>
1922

20-
{% block content %}
21-
{# freeform page content goes here #}
23+
{% block attributes %}
24+
<p class="hxSubdued hxSubBody">
25+
<hx-icon type="info-circle"></hx-icon>
26+
This element does not have any configurable attributes.
27+
</p>
2228
{% endblock %}
29+
</section>
2330

24-
{# ATTRIBUTES #}
25-
<section>
26-
<header>
27-
<h2 id="attributes">Attributes</h2>
28-
<p>
29-
Attributes enable declarative configuration of an element,
30-
via HTML markup.
31-
</p>
32-
</header>
33-
34-
{% block attributes %}
35-
<p class="hxSubdued hxSubBody">
36-
<hx-icon type="info-circle"></hx-icon>
37-
This element does not have any configurable attributes.
38-
</p>
39-
{% endblock %}
40-
</section>
41-
42-
{# PROPERTIES #}
43-
<section>
44-
<header>
45-
<h2 id="properties">Properties</h2>
46-
<p>
47-
JavaScript properties enable programmatic access to an element's
48-
configuration and state.
49-
</p>
50-
</header>
51-
52-
{% block properties %}
53-
<p class="hxSubdued hxSubBody">
54-
<hx-icon type="info-circle"></hx-icon>
55-
This element does not have any configurable properties.
56-
</p>
57-
{% endblock %}
58-
</section>
59-
60-
{% if page.also %}
61-
{% include 'partials/see-also.njk' %}
62-
{% endif %}
63-
</main>
64-
65-
<aside class="hxSiderail">
31+
{# PROPERTIES #}
32+
<section>
6633
<header>
67-
<h1 class="hxHeading-4">On this page:</h1>
34+
<h2 id="properties">Properties</h2>
35+
<p>
36+
JavaScript properties enable programmatic access to an element's
37+
configuration and state.
38+
</p>
6839
</header>
6940

70-
<nav class="article-toc">
71-
{{ page.raw | toc | safe }}
72-
<a href="#attributes">Attributes</a>
73-
<a href="#properties">Properties</a>
74-
{% if page.also %}
75-
<a href="#see-also">See Also</a>
76-
{% endif %}
77-
<hr class="hxDivider" />
78-
<a class="top-link" href="#top">Back to Top</a>
79-
</nav>
80-
</aside>
41+
{% block properties %}
42+
<p class="hxSubdued hxSubBody">
43+
<hx-icon type="info-circle"></hx-icon>
44+
This element does not have any configurable properties.
45+
</p>
46+
{% endblock %}
47+
</section>
8148
{% endblock %}

0 commit comments

Comments
 (0)