A framework for building technical documentation and tool UIs



techdocs demo

<header class="o-header-services" data-o-component="o-header">
	<div class="o-header-services__top o-header-services__container">
		<div class="o-header-services__ftlogo"></div>
		<div class="o-header-services__title">
			<h1 class="o-header-services__product-name"><a href="/">Documentation site</a></h1><span class="o-header-subrand__product-tagline ">Tagline to explain the docs</span>
		<div class="o-header-services__related-content">
			<a class="o-header-services__related-content-link" href="#">Related site</a>
			<a class="o-header-services__related-content-link" href="#">Sign in</a>

<!-- Hero banner to promote your service in a few words -->
<div class="o-techdocs-hero">
	<h2 class="o-techdocs-hero__title">
		This is a great documentation.
		It has words in it, and then more words.

<!-- Navigation menu and main content -->
<div class="o-techdocs-container">
	<div class="o-techdocs-layout">

		<!-- Navigation - optional, omit for single page docs.  o-techdocs-sidebar container allows an in-page navigation list to be appended after the site navigation -->
		<div class="o-techdocs-sidebar">
			<ul class="o-techdocs-nav">
				<li><a href="#">Link title 1</a></li>
				<li><a href="#">Link title 2</a></li>
				<li><a href="#">Link title 3</a></li>
				<li><a href="#">Link title 4</a>
					<ul class="o-techdocs-nav o-techdocs-nav--sub">
						<li><a href="#">Sub link 1</a></li>
						<li aria-selected="true"><a href="#">Sub link 2 (selected)</a></li>
						<li><a href="#">Sub link 3</a></li>
						<li><a href="#">Sub link 4</a></li>
				<li><a href="#">Link title 5</a></li>

		<!-- Main content (outer div for layout, inner for formatting) -->
		<div class="o-techdocs-main">
			<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.2.0/css/font-awesome.css">
			<div class="o-techdocs-content">

			<h1>Sample content (h1)</h1>

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

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

			<h2 id="headings">Headings (h2)</h2>

			<h3>Headings (h3)</h3>

			<h4>Headings (h4)</h4>

			<p>For best results and to enable in-page navigation to be automatically created, use <code>H1</code> once at the top of the document and then correctly nest any uses of <code>H2</code> to <code>H4</code>.  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).

			<h2 id="tables">Tables</h2>

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

					<tr><th>Repo name</th><th>Host name</th><th class="right-align">Count</th></tr>
					<tr><td>tweet-service</td><td>tweet.webservices.ft.com</td><td class="right-align">65</td></tr>
					<tr><td>nav-service</td><td>nav.webservices.ft.com</td><td class="right-align">5,231</td></tr>
					<tr><td>mostpopular-service</td><td>mostpopular.webservices.ft.com</td><td class="right-align">7</td></tr>

			<p>Add <code>scope=&quot;row&quot;</code> to <code>tr</code> tags to indicate header cells that apply to a row rather than a column:</p>

					<tr><th scope="row">Model name</th><td>Macbook Air</td></tr>
					<tr><th scope="row">Processor name</th><td>Intel Core i7</td></tr>
					<tr><th scope="row">Total number of cores</th><td>2</td></tr>
					<tr><th scope="row">Boot ROM version</th><td>MBA61.0099.B01</td></tr>

			<p>To make tables horizontally scrollable on small screens, wrap them in <code>&lt;div class=&quot;o-techdocs-table-wrapper&quot;&gt;&lt;/div&gt;</code> or include the <strong>o-techdocs</strong> JavaScript module, which will do that for you.</p>

			<h2 id="code">Source code and syntax</h2>

			<p>For inline code, wrap the content in a <code>&lt;code&gt;</code> tag.</p>

			<p>For blocks, wrap in <code>&lt;pre&gt;&lt;code&gt;</code>:</p>

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

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

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

			<pre class="long-code"><code class="markdown">50 random words

			<h3>Syntax highlighting</h3>

			</p><p>o-techdocs brings syntax highlighting out of the box using <a href="https://highlightjs.org">Highlight.js</a>.</p>

			<h3>GitHub samples / gists</h3>

			<p>GitHub gist embeds work, but using <a href="https://gist-it.appspot.com/">Gist-It</a> is preferred.  To include one, write a <code>&lt;div&gt;</code> tag in the following form:</p>

			<pre><code>&lt;div class=&quot;o-techdocs-gist&quot; data-repo=&quot;/&quot; data-branch=&quot;&quot; data-path=&quot;&quot;&gt;&lt;/div&gt;</code></pre>

			<p>Live example:</p>

			<div class="o-techdocs-gist" data-repo="financial-times/o-techdocs" data-branch="master" data-path="/origami.json"></div>


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

			<p><code>GET /v1/polyfill<var>{minify}</var>.<var>{type}</var></code></p>

							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 <code>.min</code>, the output will be minified.
							Set to <code>js</code> or <code>css</code>.

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

			<h3>Terminal/console input and output</h3>

			<p>For terminal input, use the <code>kbd</code> (for input) and <code>output</code> (for output) tags, inside a <code>&lt;pre class=&quot;cli&quot;&gt;</code>:</p>

			<pre class="cli"><kbd>jekyll serve --watch --baseurl=&apos;&apos;</kbd>
			<output>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:
			Server running... press ctrl-c to stop.</output></pre>

			<h2 id="images">Images</h2>

			<p>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:</p>

			<p><img src="http://im.ft-static.com/content/images/a1b992be-fb2c-43a8-92d8-6044c0f10408.img" alt="Image from FT.com"></p>

			<p>Multiple images can be laid side by side in a single paragraph:</p>

				<img src="http://im.ft-static.com/content/images/76a339be-1656-11e4-8210-00144feabdc0.img" alt="">
				<img src="http://im.ft-static.com/content/images/64dba0d4-5e9c-42a8-98c8-b6859c905c56.img" alt="">
				<img src="http://im.ft-static.com/content/images/cee92e8b-517e-43ee-950c-bdd4e736299e.img" alt="">

			<h2 id="asides">Asides</h2>

			<p>Use the <code>&lt;aside&gt;</code> 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 <code>&lt;h5&gt;</code>.</p>

				<h5>Example heading for the aside</h5>
				<p>Where features or elements of design are used in multiple websites, we need to build them to be usable in all those cases, and portable between them, rather than always building features solely in the context of one product.  These components should not be seen as an intrinsic part of <em>any</em> product, but instead as part of the <b>new digital FT</b>.</p>

			<p>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 (<a href="#note-32">Demo</a>):</p>

			<aside class="o-techdocs__aside--toggleable" id="note-32">This is an extra note about something</aside>

			<h2 id="disabling-doc-styles">Disabling doc styles</h2>
			<p>To make it easier to author content in markdown, styles are applied to naked tags inside any <code>.o-techdocs-content</code> element.  However, if you want to include content that you don&apos;t want to affect with tech doc styles, you can simply close the <code>.o-techdocs-content</code> and open a new one when you want back into auto-formatting.</p>

			<p>For example, here&apos;s some code that&apos;s not formatted using doc styles:</p>

			<!-- Content outside of .o-techdocs-content is not affected by naked tag styling -->
			<p><code>Sample text in a &lt;code&gt; tag</code></p>

			<div class="o-techdocs-content">
			<p>Continue with formatted content in another <code>.o-techdocs-content</code> element after your raw content is finished.</p>

			<h2 id="cards">Cards</h2>

			<p>Cards are incedibly useful for a variety of applications, normally for teasers, records, or alerts.  For more information on good uses of cards, see <a href="https://speakerdeck.com/christse/patterns-of-card-ui-design">Patterns of card UI design</a>.  Use <code>.o-techdocs-card</code> to create a card.

			<div class="o-techdocs-card">
				<div class="o-techdocs-card__context">
					<img src="http://png-3.findicons.com/files/icons/1714/dropline_neu/128/network_server.png" alt="" class="o-techdocs-card__icon">
					<div class="o-techdocs-card__heading">
						<div class="o-techdocs-card__title">Origami registry</div>
						<div class="o-techdocs-card__subtitle">registry.origami.ft.com</div>
				<div class="o-techdocs-card__content">Standard card, with card icon and action buttons.  Cards are limited to 500px wide.</div>
				<div class="o-techdocs-card__actions">
					<button class="o-techdocs-card__actionbutton">Button 1</button>
					<button class="o-techdocs-card__actionbutton">Button 2</button>

			<div class="o-techdocs-card">
				<div class="o-techdocs-card__context">
					<div class="o-techdocs-card__icon"><i class="fa fa-calendar"></i></div>
					<div class="o-techdocs-card__heading">
						<div class="o-techdocs-card__title">Card with no content</div>
						<div class="o-techdocs-card__subtitle">Just a title and optional subtitle, using Font Awesome icon</div>
					<div class="o-techdocs-card__quickactions">
						<button class="o-techdocs-card__actionbutton">Button</button>

			<div class="o-techdocs-card">
				<div class="o-techdocs-card__context">
					<div class="o-techdocs-card__heading">
						<div class="o-techdocs-card__title">Title only, no icon or subtitle</div>
					<div class="o-techdocs-card__quickactions">
						<button class="o-techdocs-card__actionbutton">Button</button>

			<a href="" class="o-techdocs-card">
				<div class="o-techdocs-card__context">
					<div class="o-techdocs-card__heading">
						<div class="o-techdocs-card__title">Whole card is clickable</div>
				<div class="o-techdocs-card__content">
					Make the whole card clickable by using an <code>&lt;a&gt;</code> tag instead of a <code>&lt;div&gt;</code>

			</p><p>Cards can also be themed to denote severities (useful for monitoring applications) and are quite effective when combined with <a href="http://registry.origami.ft.com/components/o-grid">o-grid</a>:</p>

			<div class="o-grid-row">
				<div data-o-grid-colspan="12 M6 L4">
					<a href="" class="o-techdocs-card">
						<div class="o-techdocs-card__context">
							<div class="o-techdocs-card__heading">
								<div class="o-techdocs-card__title">FT Labs utilities</div>
								<div class="o-techdocs-card__subtitle">utils.labs.ft.com</div>
						<div class="o-techdocs-card__content">Standard clickable card</div>
				<div data-o-grid-colspan="12 M6 L4">
					<div class="o-techdocs-card o-techdocs-card--sev1">
						<div class="o-techdocs-card__context">
							<div class="o-techdocs-card__heading">
								<div class="o-techdocs-card__title">Origami registry</div>
								<div class="o-techdocs-card__subtitle">registry.origami.ft.com</div>
						<div class="o-techdocs-card__content">&quot;Severity 1&quot; theme, with actions (Icons can be used in action buttons)</div>
						<div class="o-techdocs-card__actions">
							<button class="o-techdocs-card__actionbutton"><i class="fa fa-check-circle"></i> Acknowledge</button>
							<button class="o-techdocs-card__actionbutton"><i class="fa fa-plus-circle"></i> Add</button>
				<div data-o-grid-colspan="12 M6 L4">
					<a href="" class="o-techdocs-card o-techdocs-card--sev2">
						<div class="o-techdocs-card__context">
							<div class="o-techdocs-card__heading">
								<div class="o-techdocs-card__title">Origami build service</div>
								<div class="o-techdocs-card__subtitle">origin-pr.build.origami.ft.com</div>
						<div class="o-techdocs-card__content">&quot;Severity 2&quot; theme, with a clickable card</div>

			<h2 id="embedded-content">Embedded content</h2>

			<p>You can also embed content into docs from other sources, like the <a href="http://registry.origami.ft.com">Origami registry</a>.  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.</p>



			<iframe title="o-buttons demo" style="width: 100%" scrolling="no" src="http://registry.origami.ft.com/components/o-buttons@5.0.1/demos/visual/primary?embed=1"></iframe>

			</div> <!-- /o-techdocs-content -->


	</div> <!-- /.o-techdocs-layout -->
</div> <!-- /.o-techdocs-container -->

<footer class="o-techdocs-footer">
	<div class="o-techdocs-footer__inner">
		<p class="o-techdocs-footer__secondary"><a href="http://github.com/financial-times/ft-origami">View project on GitHub</a></p>
		<p>&#xA9; THE FINANCIAL TIMES LTD. FT and &apos;Financial Times&apos; are trademarks of The Financial Times Ltd.</p>
GitHub Repository


Build Service

Add the following to your <script> and <link> tags.


How do I do that?

For more information see the Origami build service.

Manual Build Process

Run the following command in the root directory of your project, to add this dependency to your bower.json file:

bower install --save "o-techdocs"@"^7.0.7"

For more information see the Origami build process.