85 lines
7.4 KiB
XML
85 lines
7.4 KiB
XML
|
<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
|
||
|
|
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
||
|
|
<channel>
|
||
|
|
<title>Writing on Cupper</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/</link>
|
||
|
|
<description>Recent content in Writing on Cupper</description>
|
||
|
|
<generator>Hugo -- gohugo.io</generator>
|
||
|
|
<language>en-us</language>
|
||
|
|
|
||
|
|
<atom:link href="https://thepaciellogroup.github.io/cupper/patterns/writing/index.xml" rel="self" type="application/rss+xml" />
|
||
|
|
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>Project structure</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/project-structure/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/project-structure/</guid>
|
||
|
|
<description>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&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>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>Markdown & metadata</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/markdown-and-metadata/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/markdown-and-metadata/</guid>
|
||
|
|
<description>In Cupper 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.
|
||
|
|
If you&rsquo;re not familiar with writing markdown, there are a number of tutorials available.</description>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>Expandable sections</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/expandable-sections/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/expandable-sections/</guid>
|
||
|
|
<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. Cupper 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>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>Notes & warnings</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/notes-and-warnings/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/notes-and-warnings/</guid>
|
||
|
|
<description>Cupper 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, Cupper 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>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>References</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/references/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/references/</guid>
|
||
|
|
<description>Cross-references Cupper 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>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>Snippets</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/snippets/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/snippets/</guid>
|
||
|
|
<description>A lot of the time, your larger documentation patterns will share some common techniques and utilities. For this reason, Cupper 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>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
<item>
|
||
|
|
<title>Tables of contents</title>
|
||
|
|
<link>https://thepaciellogroup.github.io/cupper/patterns/writing/tables-of-contents/</link>
|
||
|
|
<pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
|
||
|
|
|
||
|
|
<guid>https://thepaciellogroup.github.io/cupper/patterns/writing/tables-of-contents/</guid>
|
||
|
|
<description>Pattern pages in Cupper 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>
|
||
|
|
</item>
|
||
|
|
|
||
|
|
</channel>
|
||
|
|
</rss>
|