https://thepaciellogroup.github.io/infusion/ Recent content in The Infusion Pattern Library Builder on Infusion Hugo -- gohugo.io en-us Mon, 26 Jun 2017 18:27:58 +0100 https://thepaciellogroup.github.io/infusion/patterns/coding/code-blocks/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/code-blocks/ 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… ```html <button aria-pressed="false"toggle me</button ``` … will result in this: <button aria-pressed="false">toggle me</button> 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. https://thepaciellogroup.github.io/infusion/patterns/installation/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/installation/ Infusion is built using the static site engine, Hugo, and NPM. The codebase is available to download on Github. Let’s get everything installed step-by-step. Install Hugo First you need to install Hugo globally. OSX users If you are a Mac user and have Homebrew on your system, installing Hugo is simple: brew install hugo Alternatively, you can manually install Hugo from a package. You can verify the installation was successful by typing: https://thepaciellogroup.github.io/infusion/patterns/writing/project-structure/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/project-structure/ Before you can set about making documentation, you need to know where everything goes. The simplest folder structure looks like this: 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’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. https://thepaciellogroup.github.io/infusion/patterns/coding/demo-embedding/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/demo-embedding/ Sometimes just pictures of the pattern you’re documenting aren’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’s ID. {{% codePen VpVNKW %}} This will embed the identified codePen into the content wherever you placed the shortcode, with the result view showing by default: https://thepaciellogroup.github.io/infusion/patterns/setup/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/setup/ 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. “Cleaning” 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’re reading right now. https://thepaciellogroup.github.io/infusion/patterns/writing/markdown-and-metadata/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/markdown-and-metadata/ In Infusion everything is documented using markdown, as a “pattern”. To create a new pattern file, just add a file with the .md extension to the content/patterns folder. It’s recommended you use “kebab case” to name the file (words separated by hyphens). For example, a pattern with the title “Menu button” should probably have the filename menu-button. Then you get a nice clean URL: username.github.io/your-library/patterns/menu-button. If you’re not familiar with writing markdown, there are a number of tutorials available. https://thepaciellogroup.github.io/infusion/patterns/serving/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/serving/ Serving locally While you’re creating content for your project, you’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. https://thepaciellogroup.github.io/infusion/patterns/coding/writing-inline-demos/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/writing-inline-demos/ There are some issues with , like them not working offline. They also come with CodePen branding, which will clash with the pattern you’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’t have to worry about broken styles and global JS. https://thepaciellogroup.github.io/infusion/patterns/printing/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/printing/ Infusion’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! https://thepaciellogroup.github.io/infusion/patterns/updating/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/updating/ The core of Infusion’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 “hack the core”. 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. https://thepaciellogroup.github.io/infusion/patterns/writing/expandable-sections/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/expandable-sections/ In some cases, where there is a lot of content, it’s helpful to collapse certain sections. That way, readers get an overview of what’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. https://thepaciellogroup.github.io/infusion/print-version/ Sat, 29 Jul 2017 22:48:43 +0100 https://thepaciellogroup.github.io/infusion/print-version/ You don’t want to edit this file :-) https://thepaciellogroup.github.io/infusion/patterns/coding/color-palettes/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/color-palettes/ There’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. {{% colors "#111111, #cccccc, #ffffff" %}} The result is a one row strip showing each color supplied in order. The colors for Infusion are greyscale: https://thepaciellogroup.github.io/infusion/patterns/coding/command-line/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/command-line/ 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’s how you write it: {{<cmd}} npm run start {{</cmd}} And here’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. https://thepaciellogroup.github.io/infusion/patterns/coding/file-trees/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/file-trees/ 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: {{% fileTree %}} * Level 1 folder * Level 2 file * Level 2 folder * Level 3 file * Level 3 folder * Level 4 file * Level 3 folder * Level 4 file * Level 4 file * Level 3 file * Level 2 folder * Level 3 file * Level 3 file * Level 3 file * Level 2 file * Level 1 file {{% /fileTree %}} This is drawn in the following fashion, but preserves the underlying nested list structure for assistive technologies such as screen readers: https://thepaciellogroup.github.io/infusion/patterns/media/including-images/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/media/including-images/ From time to time, you’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’ll be mostly working in. content static images logo.png menu-button.gif When you first make a copy of Infusion, Infusion’s own logo will be included. You should replace this with your own company or project logo. https://thepaciellogroup.github.io/infusion/patterns/media/including-videos/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/media/including-videos/ Infusion has a lot of its own shortcodes, but you can still use Hugo’s built in shortcodes. These include a simple shortcode for including YouTube videos in your content. The shortcode takes just one parameter — the video’s id. {{<youtube w7Ft2ymGmfc}} https://thepaciellogroup.github.io/infusion/patterns/writing/notes-and-warnings/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/notes-and-warnings/ Infusion acknowledges that simple markdown is limiting when it comes to writing compelling documentation, so it provides a number of “shortcodes”. 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’s documentation as a note — an aside to the main thrust of the pattern’s description. This is possible using the following syntax: https://thepaciellogroup.github.io/infusion/patterns/writing/references/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/references/ Cross-references Infusion identifies the main content files in your documentation as patterns, and they’re kept in the content/ patterns folder. It’s easy to cross-reference patterns using the pattern shortcode. For example, I can reference the Notes & warnings pattern. Here’s what the markdown looks like, including the shortcode: I can reference the {{% 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. https://thepaciellogroup.github.io/infusion/patterns/writing/snippets/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/snippets/ 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’s nice to be able to just drop a snippet into your markdown content. https://thepaciellogroup.github.io/infusion/patterns/writing/tables-of-contents/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/writing/tables-of-contents/ Pattern pages in Infusion that have two or more subheadings (<h2>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 “Table of contents” label and uses an ordered list. The table of contents markup for the Setup page looks something like this: <nav class="toc" aria-labelledby="toc-heading"> <h2 id="toc-heading">Table of contents</h2> <ol> <li> <a href="#cleaning-the-content-folder">“Cleaning” the content folder</a> </li> <li> <a href="#the-setup-command">The setup command</a> </li> <li> <a href="#the-config-file">The config file</a> </li> <li> <a href="#including-a-logo">Including a logo</a> </li> </ol> </nav> Tables of content are a neat way to break down the content of the page and give users a navigable overview. https://thepaciellogroup.github.io/infusion/patterns/coding/tested/ Mon, 01 Jan 0001 00:00:00 +0000 https://thepaciellogroup.github.io/infusion/patterns/coding/tested/ When you’re an inclusive designer, it’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’ve tried your design out in. Here’s an example. Note the commas and “+” signs. {{% tested using="Firefox + JAWS, Chrome, Safari iOS + Voiceover, Edge" %}} This outputs: