<description>Markdown already supports code samples both inline (using single backticks like `some code here`) and in blocks. Infusion will syntax highlight HTML, CSS, and JavaScript if you provide the correct language in the formulation of the block.
So, this&hellip;
```html &lt;button aria-pressed="false"toggle me&lt;/button ``` &hellip; will result in this:
&lt;button aria-pressed=&quot;false&quot;&gt;toggle me&lt;/button&gt; Note that the syntax highlighting uses a greyscale theme. Infusion is careful not to use color as part of its own design, because these colors may clash with those of the design being illustrated and discussed.</description>
<description>Infusion is built using the static site engine, Hugo, and NPM. The codebase is available to download on Github. Let&rsquo;s get everything installed step-by-step.
content _index.md print-version.md patterns name-of-my-pattern.md name-of-my-other-pattern.md /content - This is where all of your content lives. You won&rsquo;t need to visit any other folders very frequently. _index.md — This is the content file for your home page. print-version.md — This is a placeholder for the single-page / print-friendly version of you library.</description>
<description>Sometimes just pictures of the pattern you&rsquo;re documenting aren&rsquo;t enough. Interactive patterns benefit from live demos, so that readers can test their functionality.
CodePen Infusion offers a couple of ways to do this. The first is by embedding CodePen demos into the content. The codePen shortcode takes just one argument: the codePen&rsquo;s ID.
&#x7b;{% codePen VpVNKW %}} This will embed the identified codePen into the content wherever you placed the shortcode, with the result view showing by default:</description>
<description>By now, you should have followed the Installation instructions. You should have Hugo and Node installed, and a local copy of a forked version of Infusion. You should also have run npm install in the root of that codebase.
&ldquo;Cleaning&rdquo; the content folder Before you can start writing documentation, there are a few things still to do in order to get set up. At the moment, your version of Infusion is a facsimile of the original, containing all the content you&rsquo;re reading right now.</description>
<description>In Infusion everything is documented using markdown, as a &ldquo;pattern&rdquo;. To create a new pattern file, just add a file with the .md extension to the content/patterns 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 menu-button. Then you get a nice clean URL: username.github.io/your-library/patterns/menu-button.
<description>Serving locally While you&rsquo;re creating content for your project, you&rsquo;ll probably want to see what the finished product looks like. Fortunately, Infusion is easy to serve locally using the serve command:
npm run serve This will serve your working project from localhost:1313. Whenever you make changes to your files, the site will automatically rebuild. No need to refresh the web page!
Publishing on Github Pages Infusion creates a /docs folder containing the latest version of your site whenever you do an npm run build or a git commit.</description>
<description>There are some issues with Demo embedding, like the embeds not working offline. They also come with their own branding, which will clash with the pattern you&rsquo;re trying to illustrate.
Infusion offers another option: a special demo shortcode that allows you to write HTML, CSS, and JavaScript directly into the markdown file. The outputted demo is encapsulated using Shadow DOM, so you don&rsquo;t have to worry about broken styles and global JS.</description>
<description>Infusion&rsquo;s output site includes a one-page Print version of the generated library, available at /print-version. So, if your library base URL is https://yourName.github.io/your-library, you can print the whole library — to PDF if wanted — from the following address:
https://yourName.github.io/your-library/print-version Print styles are also provided for individual pattern pages so, if you wanted to print off a single pattern document, you can!
<description>The core of Infusion&rsquo;s functionality is in its Hugo theme, also called Infusion. This is found in the theme folder.
content docs lib snippets static themes infusion Do not &ldquo;hack the core&rdquo;. If you have any issues with Infusion, please report them to the Infusion Github repository and they will be dealt with ASAP.
Infusion is undergoing constant development, so keep an eye out for new releases.</description>
<description>In some cases, where there is a lot of content, it&rsquo;s helpful to collapse certain sections. That way, readers get an overview of what&rsquo;s in the content and can choose where to focus in. Infusion provides a shortcode method for creating expandable sections which generates accessible markup using aria-expanded.
The expandable shortcode takes three parameters:
label — This is the label for the the section heading. level — This is the heading level (e.</description>
<description>There&rsquo;s no reason why your Infusion-powered pattern library has to be all about functionality. You can include style guide-like information such as color palettes too. The colors shortcode makes it easy to exhibit colors and their values together. Just supply a comma-separated list of CSS color values.
&#x7b;{% colors "#111111, #cccccc, #ffffff" %}} The result is a one row strip showing each color supplied in order. The colors for Infusion are greyscale:</description>
<description>Your pattern documentation may need to include commands for installing packages or using CLIs. Infusion offers the cmd shortcode for making code blocks look like terminal commands.
Here&rsquo;s how you write it:
&#x7b;{&lt;cmd}} npm run start &#x7b;{&lt;/cmd}} And here&rsquo;s how it looks:
npm run start The cmd shortcode currently only supports single commands. If you want to show multiple, successive commands use separate cmd blocks.
<description>Representing folder/file structures is simple and accessible in Infusion. Which is just as well, because some components may need to conform to a certain folder structure.
The file tree is described using a markdown nested list structure:
<description>From time to time, you&rsquo;ll be wanting to include images illustrating the documented pattern in hand. Images live in the static folder, which is a sibling of the /content folder you&rsquo;ll be mostly working in.
content static images logo.png menu-button.gif When you first make a copy of Infusion, Infusion&rsquo;s own logo will be included. You should replace this with your own company or project logo.</description>
<description>Infusion has a lot of its own shortcodes, but you can still use Hugo&rsquo;s built in shortcodes. These include a simple shortcode for including YouTube videos in your content. The shortcode takes just one parameter — the video&rsquo;s id.
<description>Infusion acknowledges that simple markdown is limiting when it comes to writing compelling documentation, so it provides a number of &ldquo;shortcodes&rdquo;. Shortcodes offer a simple syntax for including rich content. For example, Infusion provides shortcodes for including notes and warnings.
Notes You may wish to pick out some content in your pattern&rsquo;s documentation as a note — an aside to the main thrust of the pattern&rsquo;s description. This is possible using the following syntax:</description>
<description>Cross-references Infusion identifies the main content files in your documentation as patterns, and they&rsquo;re kept in the content/ patterns folder. It&rsquo;s easy to cross-reference patterns using the pattern shortcode. For example, I can reference the Notes &amp; warnings pattern. Here&rsquo;s what the markdown looks like, including the shortcode:
I can reference the &#x7b;{% pattern "Notes & warnings" %}} pattern here. This saves you having to worry about pathing and decorates the generated link with a bookmark icon, identifying the link as a pattern reference visually.</description>
<description>A lot of the time, your larger documentation patterns will share some common techniques and utilities. For this reason, Infusion lets you save snippets of markdown in a snippets folder, alongside the main content folder.
The example visually-hidden.md snippet describes the CSS needed to create content that is visually hidden but still available to screen readers. Since this is a technique/utility you are likely to use often, it&rsquo;s nice to be able to just drop a snippet into your markdown content.</description>
<description>Pattern pages in Infusion that have two or more subheadings (&lt;h2&gt;s) automatically get a table of contents: a list of links to the main subsections for the page. This feature is made accessible as a navigation region with the &ldquo;Table of contents&rdquo; label and uses an ordered list. The table of contents markup for the Setup page looks something like this:
&lt;nav class=&quot;toc&quot; aria-labelledby=&quot;toc-heading&quot;&gt; &lt;h2 id=&quot;toc-heading&quot;&gt;Table of contents&lt;/h2&gt; &lt;ol&gt; &lt;li&gt; &lt;a href=&quot;#cleaning-the-content-folder&quot;&gt;“Cleaning” the content folder&lt;/a&gt; &lt;/li&gt; &lt;li&gt; &lt;a href=&quot;#the-setup-command&quot;&gt;The setup command&lt;/a&gt; &lt;/li&gt; &lt;li&gt; &lt;a href=&quot;#the-config-file&quot;&gt;The config file&lt;/a&gt; &lt;/li&gt; &lt;li&gt; &lt;a href=&quot;#including-a-logo&quot;&gt;Including a logo&lt;/a&gt; &lt;/li&gt; &lt;/ol&gt; &lt;/nav&gt; Tables of content are a neat way to break down the content of the page and give users a navigable overview.</description>
<description>When you&rsquo;re an inclusive designer, it&rsquo;s pertinent to do some testing. Following specs is one thing, but you need to verify that your component works okay for users.
Infusion provided a tested shortcode that lets you show which browsers and assistive technologies you&rsquo;ve tried your design out in. Here&rsquo;s an example. Note the commas and &ldquo;+&rdquo; signs.
