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.

Buttons