diff --git a/config.toml b/config.toml index 4060e92..091bb4f 100644 --- a/config.toml +++ b/config.toml @@ -1,7 +1,7 @@ languageCode = "en-us" -title = "Inclusive Pattern Docs" +title = "Infusion" baseURL = "/" -theme = "inclusive-pattern-docs" +theme = "infusion" [params] description = "Documentation for the Infusion pattern library builder. This documentation is constructed using the builder itself." diff --git a/content/_index.md b/content/_index.md index a15e187..f33ce86 100644 --- a/content/_index.md +++ b/content/_index.md @@ -3,6 +3,15 @@ date = "2017-06-26T18:27:58+01:00" title = "The Infusion Pattern Library Builder" +++ -Welcome to **Infusion**: a pattern library builder with a focus on inclusive interface design. These are **Infusion's** docs, but they are also an example of a pattern library built with **Infusion**. +Welcome to **Infusion**: a pattern library builder with a focus on inclusive interface design. These are **Infusion's** docs, but they are also an example of a pattern library built with **Infusion**. Here's are some of the features: -To get started using **Infusion**, you'll first need to look at the {{% patternLink "Installation" %}} pattern. +{{% ticks %}} +* Built with Hugo, so easy to structure content and fast to compile it +* Include live code demos easily, using either CodePen embeds or via inline demo shortcodes (that use Shadow DOM) +* Quickly include WCAG and Inclusive Design Principles references by key +* Easily make sections collapsible without writing HTML +* Choose between plain or line-numbered code blocks +* A responsive, screen reader and keyboard accessible output site +{{% /ticks %}} + +To get started using **Infusion**, you'll first need to look at the {{% pattern "Installation" %}} pattern. diff --git a/content/patterns/installation.md b/content/patterns/installation.md index 8263a62..46e38ea 100644 --- a/content/patterns/installation.md +++ b/content/patterns/installation.md @@ -32,7 +32,7 @@ It is entirely likely you already have Node and NPM installed on your system. If {{}}git clone https://github.com/[your username]/infusion-builder.git{{}} -If the command line is not your thing, fork [github.com/heydon/inclusive-pattern-library](https://github.com/heydon/inclusive-pattern-library) in the browser and choose **Open in Desktop** from **Clone or download** (see figure 1, below). +If the command line is not your thing, fork [github.com/heydon/inclusive-pattern-library](https://github.com/heydon/inclusive-pattern-library) and choose **Open in Desktop** from **Clone or download** (see figure 1, below). {{% figure caption="The Github web interface" %}} ![The open in desktop option, revealed when clicking clone or download](/images/open_in_desktop.png) @@ -46,4 +46,4 @@ Once you have your local copy of the files, move to the root of that folder and {{}}npm install{{}} -Now it's time to consult the {{% patternLink "Library setup" %}} pattern. +Now it's time to consult the {{% pattern "Library setup" %}} pattern. diff --git a/content/patterns/project-setup.md b/content/patterns/project-setup.md index 28a71b4..4eafcec 100644 --- a/content/patterns/project-setup.md +++ b/content/patterns/project-setup.md @@ -2,7 +2,7 @@ title = "Library setup" +++ -By now, you should have followed the {{% patternLink "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. +By now, you should have followed the {{% pattern "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 @@ -14,7 +14,7 @@ If you are contributing to an existing **Infusion** library, do not run the foll {{}}npm run clean{{}} -This will leave your `content` folder with just an `_index.md` file and a `patterns` folder containing a single demonstration pattern file. Find out more about these in {{% patternLink "Library structure" %}}. +This will leave your `content` folder with just an `_index.md` file and a `patterns` folder containing a single demonstration pattern file. Find out more about these in {{% pattern "Library structure" %}}. ## The `setup` command @@ -46,4 +46,4 @@ theme = "infusion" In the `static` folder, you'll find a `logo.png` file. Replace this file with your own company or project logo. Currently, only the PNG format is supported. -Now that your logo's in place, everything should be ready. Where next? You can learn about {{% patternLink "Library structure" %}} to help you get writing, or find out how to serve the library locally and on Github Pages in {{% patternLink "Serving" %}}. +Now that your logo's in place, everything should be ready. Where next? You can learn about {{% pattern "Library structure" %}} to help you get writing, or find out how to serve the library locally and on Github Pages in {{% pattern "Serving" %}}. diff --git a/content/patterns/writing/including-images.md b/content/patterns/writing/including-images.md new file mode 100644 index 0000000..0342f65 --- /dev/null +++ b/content/patterns/writing/including-images.md @@ -0,0 +1,52 @@ ++++ +title = "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 +``` + +{{% note %}} +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. +{{% /note %}} + +The path to the `/images` folder should begin with a forward slash, so include that when referencing images in your markdown. + +``` +![Global Megacorp Ltd](/images/logo.png) +``` + +## Figures + +Sometimes you will want to include a caption with your illustration. This is what the `
` and `
` elements are for. However, **Infusion** doesn't ask you to code all that manually. A special shortcode is provided, which takes a `caption` parameter. Note that the image markdown is provided between the opening and closing shortcode tags: + +{{}} +{{% figure caption="Steve Faulkner works for The Paciello Group" %}} +![Steve Faulkner's face](/images/steve_faulkner.jpg) +{{% /figure %}} +{{}} + +This will output the following. Note the automatically incremented **Figure** number. + +{{% figure caption="Steve Faulkner works for The Paciello Group" %}} +![Steve Faulkner's face](/images/steve_faulkner.jpg) +{{% /figure %}} + +The generated markup includes special provisions for assistive technology support: + +```html +
+

+ Steve Faulkner's face +

+
+ Steve Faulkner works for The Paciello Group +
+
+``` diff --git a/content/patterns/writing/library-structure.md b/content/patterns/writing/library-structure.md index 3ba5a85..6b4f75b 100644 --- a/content/patterns/writing/library-structure.md +++ b/content/patterns/writing/library-structure.md @@ -1,5 +1,6 @@ +++ title = "Library structure" +weight = 1 +++ Before you can set about documenting patterns, you need to know where everything goes. The simplest folder structure looks like this: @@ -12,8 +13,9 @@ Before you can set about documenting patterns, you need to know where everything └── name-of-my-other-pattern.md ``` -* **_index.md** — This is the content for your home page -* **/patterns** — This is the folder where individual pattern files are kept +* **/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. ## Subsections @@ -45,4 +47,4 @@ The `/patterns` folder itself does not need indexing explicitly in this way. **Infusion** does not currently support _sub_-subsections. {{% /note %}} -Now that you know where to put everything, it's time to talk about how to actually write individual patterns. Don't worry, it's pretty straightforward. Turn to {{% patternLink "Markdown & metadata" %}}. +Now that you know where to put everything, it's time to talk about how to actually write individual patterns. Don't worry, it's pretty straightforward. Turn to {{% pattern "Markdown & metadata" %}}. diff --git a/content/patterns/writing/markdown-and-metadata.md b/content/patterns/writing/markdown-and-metadata.md index f985830..6f5f577 100644 --- a/content/patterns/writing/markdown-and-metadata.md +++ b/content/patterns/writing/markdown-and-metadata.md @@ -28,4 +28,20 @@ tags = ["interactive", "popup", "javascript"] +++ ``` -This will create links to tag pages listing content tagged with the same terms. +This will create links to pages listing content tagged with the same terms using the URL schema `/tag/[tag name]`. + +### Weight + +By default, patterns are listed in alphabetical order. However, sometimes you might like to change the order around. This is possible by adding a `weight` parameter. To make my menu button pattern appear at the top of its subsection, I would give it a `weight` of `1`: + +``` ++++ +title = "Menu button" +tags = ["interactive", "popup", "javascript"] +weight = 1 ++++ +``` + +{{% warning %}} +The `weight` parameter should be an integer, not a string, so don't use scare quotes around the value! +{{% /warning %}} diff --git a/content/patterns/writing/references.md b/content/patterns/writing/references.md new file mode 100644 index 0000000..b2aa594 --- /dev/null +++ b/content/patterns/writing/references.md @@ -0,0 +1,51 @@ ++++ +title = "References" ++++ + +## Cross-references + +**Infusion** provides an easy mechanism to cross-reference patterns, by name, using the `pattern` shortcode. For example, I can reference the {{% pattern "Notes and warnings" %}} pattern here. Here's what the markdown looks like, including the shortcode: + +{{}} +I can reference the {{% pattern "Notes and 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. + +## WCAG References + +[WCAG 2.0](https://www.w3.org/TR/WCAG/) is the _de facto_ standard for accessible interfaces. When writing about inclusive design patterns, sometimes you'll want to refer to WCAG to highlight which success criteria the pattern meets. + +Instead of having to copy and paste content and links to WCAG, **Infusion** provides a shortcode mechanism that lets you simply list the success criteria by number: + +{{}} +{{% wcag include="1.2.1, 1.3.1, 4.1.2" %}} +{{}} + +This generates a list of references that includes the names of each criterion and links to them directly. Like this: + +{{% wcag include="2.1.1, 4.1.2" %}} + +### Full descriptions + +Sometimes, you'll want to include the full descriptions of the success criteria inline. This is possible by setting `descriptions` to `true`: + +{{}} +{{% wcag include="1.3.1, 4.1.2" descriptions="true" %}} +{{}} + +Here's the more verbose output: + +{{% wcag include="2.1.1, 4.1.2" descriptions="true" %}} + +## Inclusive Design Principle references + +Some inclusive design concepts are not reducible to success or fail criteria. This is why The Paciello Group wrote the [Inclusive Design Principles](http://inclusivedesignprinciples.org/). These can be listed by name. + +{{}} +{{% principles include="Add value, Be consistent" descriptions="true" %}} +{{}} + +Here's the output with `descriptions="true"`: + +{{% principles include="Add value, Be consistent" descriptions="true" %}} diff --git a/static/images/steve_faulkner.jpg b/static/images/steve_faulkner.jpg new file mode 100644 index 0000000..d2d07d4 Binary files /dev/null and b/static/images/steve_faulkner.jpg differ diff --git a/themes/inclusive-pattern-docs/layouts/partials/svg.html b/themes/inclusive-pattern-docs/layouts/partials/svg.html deleted file mode 100644 index dd2f6c2..0000000 --- a/themes/inclusive-pattern-docs/layouts/partials/svg.html +++ /dev/null @@ -1,22 +0,0 @@ - - - - - - - - - W3C - SVG - - - - - - - - - - - - diff --git a/themes/inclusive-pattern-docs/LICENSE.md b/themes/infusion/LICENSE.md similarity index 100% rename from themes/inclusive-pattern-docs/LICENSE.md rename to themes/infusion/LICENSE.md diff --git a/themes/inclusive-pattern-docs/archetypes/default.md b/themes/infusion/archetypes/default.md similarity index 100% rename from themes/inclusive-pattern-docs/archetypes/default.md rename to themes/infusion/archetypes/default.md diff --git a/themes/inclusive-pattern-docs/archetypes/patterns.md b/themes/infusion/archetypes/patterns.md similarity index 100% rename from themes/inclusive-pattern-docs/archetypes/patterns.md rename to themes/infusion/archetypes/patterns.md diff --git a/themes/inclusive-pattern-docs/data/principles.json b/themes/infusion/data/principles.json similarity index 100% rename from themes/inclusive-pattern-docs/data/principles.json rename to themes/infusion/data/principles.json diff --git a/themes/inclusive-pattern-docs/data/wcag.json b/themes/infusion/data/wcag.json similarity index 100% rename from themes/inclusive-pattern-docs/data/wcag.json rename to themes/infusion/data/wcag.json diff --git a/themes/inclusive-pattern-docs/layouts/404.html b/themes/infusion/layouts/404.html similarity index 100% rename from themes/inclusive-pattern-docs/layouts/404.html rename to themes/infusion/layouts/404.html diff --git a/themes/inclusive-pattern-docs/layouts/_default/baseof.html b/themes/infusion/layouts/_default/baseof.html similarity index 96% rename from themes/inclusive-pattern-docs/layouts/_default/baseof.html rename to themes/infusion/layouts/_default/baseof.html index 3c6eedf..b4d2c2a 100644 --- a/themes/inclusive-pattern-docs/layouts/_default/baseof.html +++ b/themes/infusion/layouts/_default/baseof.html @@ -30,7 +30,7 @@ {{ $current := . }} {{ range $.Site.Home.Sections }}