/ Recent content in The Infusion Pattern Library Builder on Infusion Hugo -- gohugo.io en-us Mon, 26 Jun 2017 18:27:58 +0100 /patterns/writing/library-structure/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/writing/library-structure/ 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. /patterns/writing/markdown-and-metadata/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/writing/markdown-and-metadata/ 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. /patterns/writing/expandable-sections/ Mon, 01 Jan 0001 00:00:00 +0000 /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. /patterns/code/code-blocks/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/code/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. /patterns/code/codepen-embedding/ Mon, 01 Jan 0001 00:00:00 +0000 /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: /patterns/writing/including-images/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/writing/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. /patterns/installation/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/installation/ 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: brew install hugo Alternatively, you can manually install Hugo from a package. You can verify the installation was successful by typing: /patterns/library-setup/ Mon, 01 Jan 0001 00:00:00 +0000 /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. /patterns/writing/notes-and-warnings/ Mon, 01 Jan 0001 00:00:00 +0000 /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: /patterns/writing/references/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/writing/references/ 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. /patterns/serving/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/serving/ 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. /patterns/code/writing-inline-demos/ Mon, 01 Jan 0001 00:00:00 +0000 /patterns/code/writing-inline-demos/ 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.