Sample content (h1)

The following is sample content demonstrating all the built in styles supported by the o-techdocs module. Basics such as headings (H1 to H5), bulleted and numbered lists, inline links and <code> are obviously supported, and additonal style components have been designed to better support technical use cases rather than editorial ones.

The code examples are in the source of this page. To apply tag-based styling, wrap content in a .o-techdocs-content class. Tag-based styling will only apply to tags that are direct descendents of .o-techdocs-content. Class-based styles will work anywhere.

Headings (h2)

Headings (h3)

Headings (h4)

For best results and to enable in-page navigation to be automatically created, use H1 once at the top of the document and then correctly nest any uses of H2 to H4. If you do this properly, in-page navigation will appear on the left in dark red under the main navigation (if you have a sidebar).

Tables

Use normal HTML markup for tables. Add a right-align class to cells for right alignment, normally for numeric data.

Repo name	Host name	Count
tweet-service	tweet.webservices.ft.com	65
nav-service	nav.webservices.ft.com	5,231
mostpopular-service	mostpopular.webservices.ft.com	7

Add scope="row" to tr tags to indicate header cells that apply to a row rather than a column:

Model name	Macbook Air
Processor name	Intel Core i7
Total number of cores	2
Boot ROM version	MBA61.0099.B01

To make tables horizontally scrollable on small screens, wrap them in <div class="o-techdocs-table-wrapper"></div> or include the o-techdocs JavaScript module, which will do that for you.

Source code and syntax

For inline code, wrap the content in a <code> tag.

For blocks, wrap in <pre><code>:

$.ajax({
				"url": "/api/getWeather",
				"data": {
					"zipcode": 97201
				},
				"success": function( data ) {
					$("#weather-temp").html("" + data + " degrees");
				} // A nice comment
			});

Any such blocks added to the DOM after techdocs has initialised will be detected and highlighted automatically.

For large code samples, the code block may be constrained to a reasonable height and made to scroll vertically by adding a long-code class to the pre tag (here we also opt out of syntax highlighting and line numbering):

50 random words
			===============
			aquacade
			volatilise
			boniface
			centesimo
			unfaked
			unraftered
			upstart
			hemocyanin
			meaninglessness
			whitehead
			oxime
			angelus
			obtundent
			readvertisement
			limited
			misemphasized
			subintegumental
			nates
			ethyle
			gasolineless
			biophysics
			reprography
			soluble
			qualitative
			vaporetto
			raphaelle
			equipollency
			taipei
			lunacy
			symploce
			overconcentrated
			logograph
			ashur
			uncondemned
			nipigon
			gomerel
			impregnation
			insaneness
			avifaunally
			projectable
			disputing
			sprightful
			nonschematically
			normandy
			basis
			discomposing
			stroking
			auberon
			bioptic
			pockier

Syntax highlighting

o-techdocs brings syntax highlighting out of the box using Highlight.js.

GitHub samples / gists

GitHub gist embeds work, but using Gist-It is preferred. To include one, write a <div> tag in the following form:

<div class="o-techdocs-gist" data-repo="/" data-branch="" data-path=""></div>

Live example:

Variables

To highlight variables that should be replaced by real values, use the var tag. This is often used as part of part of a table, to document parameters to an API or method:

GET /v1/polyfill{minify}.{type}

Param	Where	Description
minify	URL	Whether to minify the result. If omitted, output will include the full polyfill source, and a header comment with debug information about the user agent and which polyfills have been included in the bundle. If set to .min, the output will be minified.
type	URL	Set to js or css.

Unlike code, text marked up as var cannot wrap, so should be restricted to short names unlikely to fill the width of the screen.

Terminal/console input and output

For terminal input, use the kbd (for input) and output (for output) tags, inside a <pre class="cli">:

jekyll serve --watch --baseurl=''
			
Configuration file: /Users/user.name/sandboxes/local/style-guide/_config.yml
			Source: /Users/user.name/sandboxes/local/style-guide
			Destination: /Users/user.name/sandboxes/local/style-guide/_site
			Generating... done.
			Auto-regeneration: enabled
			Server address: http://0.0.0.0:4000
			Server running... press ctrl-c to stop.

Images

Images will be auto-scaled to no more than the width of the content area (but will not be scaled up). To separate images from text, wrap the image element in a paragraph tag:

Multiple images can be laid side by side in a single paragraph:

Asides

Use the <aside> tag to create inset boxed content, useful for examples, non-normative notes, warnings for the wary etc. For a heading inside the aside, use an <h5>.

To hide an aside and display only when a link is clicked, give the aside a class of `o-techdocs__aside--toggleable` and an id, which can be anything. Then create a link that targets the ID (Demo):

Disabling doc styles

To make it easier to author content in markdown, styles are applied to naked tags inside any .o-techdocs-content element. However, if you want to include content that you don't want to affect with tech doc styles, you can simply close the .o-techdocs-content and open a new one when you want back into auto-formatting.

For example, here's some code that's not formatted using doc styles:

Continue with formatted content in another .o-techdocs-content element after your raw content is finished.

Cards

Cards are incedibly useful for a variety of applications, normally for teasers, records, or alerts. For more information on good uses of cards, see Patterns of card UI design. Use .o-techdocs-card to create a card.

Whole card is clickable

Make the whole card clickable by using an <a> tag instead of a <div>

Cards can also be themed to denote severities (useful for monitoring applications) and are quite effective when combined with o-grid:

Embedded content

You can also embed content into docs from other sources, like the Origami registry. In the following examples, one IFRAME has a fixed width (which will be overridden and reduced if the window is too narrow to contain it) and the other has a fluid 100% width. The height of the IFRAMEs is set automatically based on their content, for which you need to include the registry embedder script.

Gallery

Buttons