cupper-hugo-theme/docs/patterns/writing/markdown-and-metadata/index.html
2017-07-16 16:49:20 +01:00

347 lines
22 KiB
HTML

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link rel="canonical" href="https://heydon.github.io/infusion/patterns/writing/markdown-and-metadata/">
<link rel="apple-touch-icon" sizes="57x57" href="https://heydon.github.io/infusion/images/apple-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="https://heydon.github.io/infusion/images/apple-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="https://heydon.github.io/infusion/images/apple-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="https://heydon.github.io/infusion/images/apple-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="https://heydon.github.io/infusion/images/apple-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="https://heydon.github.io/infusion/images/apple-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="https://heydon.github.io/infusion/images/apple-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="https://heydon.github.io/infusion/images/apple-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="https://heydon.github.io/infusion/images/apple-icon-180x180.png">
<link rel="icon" type="image/png" sizes="192x192" href="https://heydon.github.io/infusion/images/android-icon-192x192.png">
<link rel="icon" type="image/png" sizes="32x32" href="https://heydon.github.io/infusion/images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="96x96" href="https://heydon.github.io/infusion/images/favicon-96x96.png">
<link rel="icon" type="image/png" sizes="16x16" href="https://heydon.github.io/infusion/images/favicon-16x16.png">
<link rel="manifest" href="https://heydon.github.io/infusion/manifest.json">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/images/ms-icon-144x144.png">
<meta name="theme-color" content="#ffffff">
<link rel="stylesheet" href="https://heydon.github.io/infusion/css/prism.css" />
<link rel="stylesheet" type="text/css" href="https://heydon.github.io/infusion/css/styles.css">
<script src="https://heydon.github.io/infusion/js/webcomponents.js"></script>
<title>
Markdown &amp; metadata | Infusion
</title>
</head>
<body>
<a href="#main">skip to content</a>
<svg style="display: none">
<symbol id="bookmark">
<g transform="translate(2266 3206.2)">
<path style="stroke:currentColor;stroke-width:3.2637;fill:none" d="m-2262.2-3203.4-.2331 42.195 16.319-16.318 16.318 16.318.2331-42.428z"/>
</g>
</symbol>
<symbol id="w3c">
<text font-size="83" style="font-size:83px;font-family:Trebuchet;letter-spacing:-12;fill-opacity:0" letter-spacing="-12" y="67.609352" x="-26.782778">W3C</text>
<text font-size="83" style="font-size:83px;font-weight:bold;font-family:Trebuchet;fill-opacity:0" y="67.609352" x="153.21722" font-weight="bold">SVG</text>
<path style="fill:#111111;image-rendering:optimizeQuality;shape-rendering:geometricPrecision" d="m33.695.377 12.062 41.016 12.067-41.016h8.731l-19.968 67.386h-.831l-12.48-41.759-12.479 41.759h-.832l-19.965-67.386h8.736l12.061 41.016 8.154-27.618-3.993-13.397h8.737z"/>
<path style="fill:#111111;image-rendering:optimizeQuality;shape-rendering:geometricPrecision" d="m91.355 46.132c0 6.104-1.624 11.234-4.862 15.394-3.248 4.158-7.45 6.237-12.607 6.237-3.882 0-7.263-1.238-10.148-3.702-2.885-2.47-5.02-5.812-6.406-10.022l6.82-2.829c1.001 2.552 2.317 4.562 3.953 6.028 1.636 1.469 3.56 2.207 5.781 2.207 2.329 0 4.3-1.306 5.909-3.911 1.609-2.606 2.411-5.738 2.411-9.401 0-4.049-.861-7.179-2.582-9.399-1.995-2.604-5.129-3.912-9.397-3.912h-3.327v-3.991l11.646-20.133h-14.062l-3.911 6.655h-2.493v-14.976h32.441v4.075l-12.31 21.217c4.324 1.385 7.596 3.911 9.815 7.571 2.22 3.659 3.329 7.953 3.329 12.892z"/>
<path style="fill:#111111;image-rendering:optimizeQuality;shape-rendering:geometricPrecision" d="m125.21 0 1.414 8.6-5.008 9.583s-1.924-4.064-5.117-6.314c-2.693-1.899-4.447-2.309-7.186-1.746-3.527.73-7.516 4.938-9.258 10.13-2.084 6.21-2.104 9.218-2.178 11.978-.115 4.428.58 7.043.58 7.043s-3.04-5.626-3.011-13.866c.018-5.882.947-11.218 3.666-16.479 2.404-4.627 5.954-7.404 9.114-7.728 3.264-.343 5.848 1.229 7.841 2.938 2.089 1.788 4.213 5.698 4.213 5.698l4.94-9.837z"/>
<path style="fill:#111111;image-rendering:optimizeQuality;shape-rendering:geometricPrecision" d="m125.82 48.674s-2.208 3.957-3.589 5.48c-1.379 1.524-3.849 4.209-6.896 5.555-3.049 1.343-4.646 1.598-7.661 1.306-3.01-.29-5.807-2.032-6.786-2.764-.979-.722-3.486-2.864-4.897-4.854-1.42-2-3.634-5.995-3.634-5.995s1.233 4.001 2.007 5.699c.442.977 1.81 3.965 3.749 6.572 1.805 2.425 5.315 6.604 10.652 7.545 5.336.945 9.002-1.449 9.907-2.031.907-.578 2.819-2.178 4.032-3.475 1.264-1.351 2.459-3.079 3.116-4.108.487-.758 1.276-2.286 1.276-2.286l-1.276-6.644z"/>
</symbol>
<symbol id="tag">
<g transform="translate(0 -875.2)">
<path style="fill-rule:evenodd;stroke-width:0;fill:#111111" d="m159.9 894.3-68.79 8.5872-75.42 77.336 61.931 60.397 75.429-76.565 6.8495-69.755zm-31.412 31.835a10.813 10.813 0 0 1 1.8443 2.247 10.813 10.813 0 0 1 -3.5174 14.872l-.0445.0275a10.813 10.813 0 0 1 -14.86 -3.5714 10.813 10.813 0 0 1 3.5563 -14.863 10.813 10.813 0 0 1 13.022 1.2884z"/>
</g>
</symbol>
<symbol id="balloon">
<g transform="translate(0 -875.2)">
<g>
<path style="fill:#1a1a1a" d="m68.156 882.83-.88753 1.4269c-4.9564 7.9666-6.3764 17.321-5.6731 37.378.36584 10.437 1.1246 23.51 1.6874 29.062.38895 3.8372 3.8278 32.454 4.6105 38.459 4.6694-.24176 9.2946.2879 14.377 1.481 1.2359-3.2937 5.2496-13.088 8.886-21.623 6.249-14.668 8.4128-21.264 10.253-31.252 1.2464-6.7626 1.6341-12.156 1.4204-19.764-.36325-12.93-2.1234-19.487-6.9377-25.843-2.0833-2.7507-6.9865-7.6112-7.9127-7.8436-.79716-.20019-6.6946-1.0922-6.7755-1.0248-.02213.0182-5.0006-.41858-7.5248-.22808l-2.149-.22808h-3.3738z"/>
<path style="fill:#1a1a1a" d="m61.915 883.28-3.2484.4497c-1.7863.24724-3.5182.53481-3.8494.63994-2.4751.33811-4.7267.86957-6.7777 1.5696-.28598 0-1.0254.20146-2.3695.58589-5.0418 1.4418-6.6374 2.2604-8.2567 4.2364-6.281 7.6657-11.457 18.43-12.932 26.891-1.4667 8.4111.71353 22.583 5.0764 32.996 3.8064 9.0852 13.569 25.149 22.801 37.517 1.3741 1.841 2.1708 2.9286 2.4712 3.5792 3.5437-1.1699 6.8496-1.9336 10.082-2.3263-1.3569-5.7831-4.6968-21.86-6.8361-33.002-.92884-4.8368-2.4692-14.322-3.2452-19.991-.68557-5.0083-.77707-6.9534-.74159-15.791.04316-10.803.41822-16.162 1.5026-21.503 1.4593-5.9026 3.3494-11.077 6.3247-15.852z"/>
<path style="fill:#1a1a1a" d="m94.499 885.78c-.10214-.0109-.13691 0-.0907.0409.16033.13489 1.329 1.0675 2.5976 2.0723 6.7003 5.307 11.273 14.568 12.658 25.638.52519 4.1949.24765 14.361-.5059 18.523-2.4775 13.684-9.7807 32.345-20.944 53.519l-3.0559 5.7971c2.8082.76579 5.7915 1.727 8.9926 2.8441 11.562-11.691 18.349-19.678 24.129-28.394 7.8992-11.913 11.132-20.234 12.24-31.518.98442-10.02-1.5579-20.876-6.7799-28.959-.2758-.4269-.57803-.86856-.89617-1.3166-3.247-6.13-9.752-12.053-21.264-16.131-2.3687-.86369-6.3657-2.0433-7.0802-2.1166z"/>
<path style="fill:#1a1a1a" d="m32.52 892.22c-.20090-.13016-1.4606.81389-3.9132 2.7457-11.486 9.0476-17.632 24.186-16.078 39.61.79699 7.9138 2.4066 13.505 5.9184 20.562 5.8577 11.77 14.749 23.219 30.087 38.74.05838.059.12188.1244.18052.1838 1.3166-.5556 2.5965-1.0618 3.8429-1.5199-.66408-.32448-1.4608-1.3297-3.8116-4.4602-5.0951-6.785-8.7512-11.962-13.051-18.486-5.1379-7.7948-5.0097-7.5894-8.0586-13.054-6.2097-11.13-8.2674-17.725-8.6014-27.563-.21552-6.3494.13041-9.2733 1.775-14.987 2.1832-7.5849 3.9273-10.986 9.2693-18.07 1.7839-2.3656 2.6418-3.57 2.4409-3.7003z"/>
<path style="fill:#1a1a1a" d="m69.133 992.37c-6.2405.0309-12.635.76718-19.554 2.5706 4.6956 4.7759 9.935 10.258 12.05 12.625l4.1272 4.6202h11.493l3.964-4.4516c2.0962-2.3541 7.4804-7.9845 12.201-12.768-8.378-1.4975-16.207-2.6353-24.281-2.5955z"/>
<rect style="stroke-width:0;fill:#1a1a1a" ry="2.0328" height="27.746" width="22.766" y="1017.7" x="60.201"/>
</g>
</g>
</symbol>
<symbol id="info">
<g transform="translate(-37.035 -1004.6)">
<path style="stroke-linejoin:round;stroke:currentColor;stroke-linecap:round;stroke-width:3.728;fill:none" d="m76.25 1030.2a18.968 18.968 0 0 1 -23.037 13.709 18.968 18.968 0 0 1 -13.738 -23.019 18.968 18.968 0 0 1 23.001 -13.768 18.968 18.968 0 0 1 13.798 22.984"/>
<g transform="matrix(1.1146 0 0 1.1146 -26.276 -124.92)">
<path style="stroke:currentColor;stroke-linecap:round;stroke-width:3.728;fill:none" d="m75.491 1039.5v-8.7472"/>
<path style="stroke-width:0;fill:currentColor" transform="scale(-1)" d="m-73.193-1024.5a2.3719 2.3719 0 0 1 -2.8807 1.7142 2.3719 2.3719 0 0 1 -1.718 -2.8785 2.3719 2.3719 0 0 1 2.8763 -1.7217 2.3719 2.3719 0 0 1 1.7254 2.8741"/>
</g>
</g>
</symbol>
<symbol id="warning">
<g transform="translate(-1.1273 -1010.2)">
<path style="stroke-linejoin:round;stroke:currentColor;stroke-linecap:round;stroke-width:4.151;fill:none" d="m25.343 1012.3-22.14 37.496h44.28z"/>
<path style="stroke:currentColor;stroke-linecap:round;stroke-width:4.1512;fill:none" d="m25.54 1027.7v8.7472"/>
<path style="stroke-width:0;fill:currentColor" d="m27.839 1042.8a2.3719 2.3719 0 0 1 -2.8807 1.7143 2.3719 2.3719 0 0 1 -1.718 -2.8785 2.3719 2.3719 0 0 1 2.8763 -1.7217 2.3719 2.3719 0 0 1 1.7254 2.8741"/>
</g>
</symbol>
<symbol id="menu">
<rect style="stroke-width:0;fill:currentColor" height="10" width="50" y="0" x="0"/>
<rect style="stroke-width:0;fill:currentColor" height="10" width="50" y="20" x="0"/>
<rect style="stroke-width:0;fill:currentColor" height="10" width="50" y="40" x="0"/>
</symbol>
</svg>
<div class="wrapper">
<header class="intro-and-nav" role="banner">
<div>
<div class="intro">
<a class="logo" href="https://heydon.github.io/infusion/" aria-label="Infusion pattern library home page">
<img src="https://heydon.github.io/infusion/images/logo.png" alt="">
</a>
<p class="library-desc">Documentation for the <strong>Infusion</strong> pattern library builder. This documentation is constructed using the builder itself.</p>
</div>
<nav id="patterns-nav" class="patterns" role="navigation">
<button id="menu-button" aria-expanded="false">
<svg viewBox="0 0 50 50">
<use xlink:href="#menu"></use>
</svg>
Menu
</button>
<ul id="patterns-list">
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/installation/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Installation</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/library-setup/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Library setup</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/serving/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Serving</span>
</a>
</li>
<li>
<h3>Writing</h3>
<ul>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/writing/library-structure/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Library structure</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/writing/markdown-and-metadata/" aria-current="page">
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Markdown &amp; metadata</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/writing/expandable-sections/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Expandable sections</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/writing/notes-and-warnings/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Notes &amp; warnings</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/writing/references/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">References</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/writing/tables-of-contents/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Tables of contents</span>
</a>
</li>
</ul>
</li>
<li>
<h3>Media</h3>
<ul>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/media/including-images/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Including images</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/media/including-videos/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Including videos</span>
</a>
</li>
</ul>
</li>
<li>
<h3>Coding</h3>
<ul>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/code-blocks/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Code blocks</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/codepen-embedding/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">CodePen embedding</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/writing-inline-demos/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Writing inline demos</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/color-palettes/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Color palettes</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/command-line/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Command line</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/file-trees/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">File trees</span>
</a>
</li>
<li class="pattern">
<a href="https://heydon.github.io/infusion/patterns/coding/tested/" >
<svg class="bookmark-icon" aria-hidden="true" viewBox="0 0 40 50"><use xlink:href="#bookmark"></use></svg>
<span class="text">Tested using...</span>
</a>
</li>
</ul>
</li>
</ul>
</nav>
</div>
</header>
<div class="main-and-footer">
<div>
<main id="main">
<h1>Markdown &amp; metadata</h1>
<p>In <strong>Infusion</strong>, design patterns are documented using markdown. To create a new pattern file, just add a file with the <code>.md</code> extension to the <code>/patterns</code> folder. It&rsquo;s recommended you use &ldquo;kebab case&rdquo; to name the file ( words separated by hyphens). For example, a pattern with the title &ldquo;Menu button&rdquo; should probably have the filename <code>menu-button</code>. Then you get a nice clean URL: <code>your-company.com/patterns/menu-button</code>.</p>
<p>If you&rsquo;re not familiar with writing markdown, there are a number of tutorials available. One of the best is <a href="https://guides.github.com/features/mastering-markdown/">Mastering Markdown</a> offered by Github. There&rsquo;s also a <a href="https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet">nice cheatsheet here</a>.</p>
<h2 id="the-metadata">The metadata</h2>
<p>Like many static site generators, Hugo lets you add metadata to its markdown files. Hugo&rsquo;s brand of metadata is called TOML (although YAML is also accepted). The only thing you <em>have</em> to put in the TOML is a <code>title</code> — like this:</p>
<pre><code>+++
title = &quot;Menu button&quot;
+++
</code></pre>
<h3 id="tags">Tags</h3>
<p>If you like, you can also tag the pattern so that it turns up in lists of similar content. You add tags in an array format. Note that all the TOML data is found at the top of the markdown file, between the <code>+++</code> lines.</p>
<pre><code>+++
title = &quot;Menu button&quot;
tags = [&quot;interactive&quot;, &quot;popup&quot;, &quot;javascript&quot;]
+++
</code></pre>
<p>This will create links to pages listing content tagged with the same terms using the URL schema <code>/tag/[tag name]</code>.</p>
<h3 id="weight">Weight</h3>
<p>By default, patterns are listed in alphabetical order. However, sometimes you might like to change the order around. This is possible by adding a <code>weight</code> parameter. To make my menu button pattern appear at the top of its subsection, I would give it a <code>weight</code> of <code>1</code>:</p>
<pre><code>+++
title = &quot;Menu button&quot;
tags = [&quot;interactive&quot;, &quot;popup&quot;, &quot;javascript&quot;]
weight = 1
+++
</code></pre>
<aside aria-label="warning" class="note warning">
<div>
<svg aria-hidden="true" height="41.646" width="48.43" viewBox="0 0 48.430474 41.646302">
<use xlink:href="#warning"></use>
</svg>
<p>The <code>weight</code> parameter should be an integer, not a string, so don&rsquo;t use scare quotes around the value!</p>
</div>
</aside>
</main>
<footer role="contentinfo">
Powered by <strong>Infusion</strong>, a <strong>The Paciello Group</strong> project.<br>
For general enquiries, contact us on info@paciellogroup.com.
</footer>
</div>
</div>
</div>
<script src="https://heydon.github.io/infusion/js/prism.js"></script>
<script src="https://heydon.github.io/infusion/js/dom-scripts.js"></script>
</body>
</html>