Categories on Infusion

Library structure

Mon, 01 Jan 0001 00:00:00 +0000

Before you can set about documenting patterns, you need to know where everything goes. The simplest folder structure looks like this: └── content ├── _index.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 for your home page. /patterns — This is the folder where individual pattern files are kept.

Markdown & metadata

Mon, 01 Jan 0001 00:00:00 +0000

In Infusion, design patterns are documented using markdown. To create a new pattern file, just add a file with the .md extension to the /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: your-company.com/patterns/menu-button. If you’re not familiar with writing markdown, there are a number of tutorials available.

Expandable sections

Mon, 01 Jan 0001 00:00:00 +0000

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: @@ -56,10 +56,10 @@ So, this… CodePen embedding - /patterns/code/codepen-embedding/ + https://heydon.github.io/inclusive-pattern-library/patterns/code/codepen-embedding/ Mon, 01 Jan 0001 00:00:00 +0000 - /patterns/code/codepen-embedding/ + https://heydon.github.io/inclusive-pattern-library/patterns/code/codepen-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. 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:

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Infusion is built using the static site engine, Hugo, and NPM. The codebase is available to download on Github. Let’s get set up step-by-step. 1. Install Hugo First we need to install Hugo globally. OSX users If you are a Mac user and have Homebrew on your system, installing Hugo is simple: @@ -89,40 +89,40 @@ brew install hugo Alternatively, you can manually install Hugo from a package. Y Library setup - /patterns/library-setup/ + https://heydon.github.io/inclusive-pattern-library/patterns/library-setup/ Mon, 01 Jan 0001 00:00:00 +0000 - /patterns/library-setup/ + https://heydon.github.io/inclusive-pattern-library/patterns/library-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 documenting patterns, 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 this documentation content.

Notes & warnings

Mon, 01 Jan 0001 00:00:00 +0000

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:

References

Mon, 01 Jan 0001 00:00:00 +0000

Cross-references Infusion provides an easy mechanism to cross-reference patterns, by title, 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.

Serving

Mon, 01 Jan 0001 00:00:00 +0000

Serving locally While you’re creating content for your library, 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 library on localhost:1313. Whenever you make changes to your library’s files, the site will automatically rebuild. No need to refresh the web page! Publishing on Github Pages The easiest way to host your pattern library so you have a link to share is to run the host command.

Code blocks

Mon, 01 Jan 0001 00:00:00 +0000

CodePen embedding

Mon, 01 Jan 0001 00:00:00 +0000

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. +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:

Writing inline demos

Mon, 01 Jan 0001 00:00:00 +0000

There are some issues with CodePen embedding , 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.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Infusion is built using the static site engine, Hugo, and NPM. The codebase is available to download on Github. Let’s get set up step-by-step. 1. Install Hugo First we need to install Hugo globally. OSX users If you are a Mac user and have Homebrew on your system, installing Hugo is simple: @@ -24,20 +24,20 @@ brew install hugo Alternatively, you can manually install Hugo from a package. Y Library setup - /patterns/library-setup/ + https://heydon.github.io/inclusive-pattern-library/patterns/library-setup/ Mon, 01 Jan 0001 00:00:00 +0000 - /patterns/library-setup/ + https://heydon.github.io/inclusive-pattern-library/patterns/library-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 documenting patterns, 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 this documentation content.

Serving

Mon, 01 Jan 0001 00:00:00 +0000

Markdown & metadata

Mon, 01 Jan 0001 00:00:00 +0000

Expandable sections

Mon, 01 Jan 0001 00:00:00 +0000

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.

Notes & warnings

Mon, 01 Jan 0001 00:00:00 +0000

References

Mon, 01 Jan 0001 00:00:00 +0000