hg.stevelosh.com > docs.stevelosh.com

<html><head><title>Usage / d</title><link rel="stylesheet" href="../_dmedia/bootstrap.css"/><link rel="stylesheet" href="../_dmedia/tango.css"/><link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/><script src="../_dmedia/less.js" type="text/javascript">
        </script></head><body class="content">
        <div class="wrap">
            <header><h1><a href="..">d</a></h1></header><h1 id="usage">Usage</h1>
<p><code>d</code> is designed to be easy and intuitive to use.  Here's a whirlwind tour that
will get you up and running in five minutes.</p>
<div class="toc">
<ul><li><a href="#basic-flow">Basic Flow</a></li>
<li><a href="#the-introduction-page">The Introduction Page</a></li>
<li><a href="#the-footer">The Footer</a></li>
<li><a href="#documentation-files">Documentation Files</a><ul><li><a href="#extensions">Extensions</a></li>
<li><a href="#layout">Layout</a></li>
<li><a href="#page-titles">Page Titles</a></li>
<li><a href="#other-headings">Other Headings</a></li>
<li><a href="#links">Links</a></li>
<li><a href="#relative-urls">Relative URLs</a></li>
<li><a href="#tables-of-contents">Tables of Contents</a></li>
</ul></li>
<li><a href="#example">Example</a></li>
</ul></div>
<h2 id="basic-flow">Basic Flow</h2>
<p>Make a directory for your docs:</p>
<div class="codehilite"><pre>mkdir docs
<span class="nb">cd </span>docs
</pre></div>


<p>Write some docs:</p>
<div class="codehilite"><pre>touch index.markdown
touch installation.markdown
touch usage.markdown

vim .
</pre></div>


<p>Render your docs:</p>
<div class="codehilite"><pre>d
</pre></div>


<p>Copy the output somewhere:</p>
<div class="codehilite"><pre>rsync -d build/ myserver:/var/www/myproject
</pre></div>


<h2 id="the-introduction-page">The Introduction Page</h2>
<p>The text of the main page (above the table of contents) comes from the
<code>index.markdown</code> file.</p>
<p>This page doesn't need a title.  Just write out the text you want to show above
the table of contents.</p>
<h2 id="the-footer">The Footer</h2>
<p>The contents of the footer comes from <code>footer.markdown</code>.</p>
<h2 id="documentation-files">Documentation Files</h2>
<p>There are a few rules to follow when writing docs for use with <code>d</code>.  They should
be pretty intuitive once you try them out.</p>
<h3 id="extensions">Extensions</h3>
<p>You can use <code>.markdown</code>, <code>.mdown</code>, or <code>.md</code> as the extension for your Markdown
files.  <code>d</code> doesn't care.</p>
<h3 id="layout">Layout</h3>
<p>Each Markdown file (other than the introduction and footer) is rendered as
a separate page.</p>
<h3 id="page-titles">Page Titles</h3>
<p>Every page other than the introduction needs a level 1 heading as the first
line.  It will be used as the title of the page.</p>
<h3 id="other-headings">Other Headings</h3>
<p>There shouldn't be any other level 1 headings.  Levels 2/3/4/5/6 are fine.</p>
<h3 id="links">Links</h3>
<p>Link to other documents by using their filenames with no extension.</p>
<p>For example: the URL for <code>usage.markdown</code> would be <code>/usage/</code>.</p>
<h3 id="relative-urls">Relative URLs</h3>
<p>If you're planning on serving these docs at a URL other than <code>/</code> you should add
<code>..</code> before links to other pages.</p>
<p>For example: the URL for <code>usage.markdown</code> would now be <code>../usage/</code>.</p>
<p><strong>Note:</strong> these relative URLs are safe to use even when you're serving the docs
at <code>/</code>, so there's no disadvantage to using them other than a bit more typing.</p>
<h3 id="tables-of-contents">Tables of Contents</h3>
<p>Use <code>[TOC]</code> to display a table of contents for the current page, if you want
one.</p>
<h2 id="example">Example</h2>
<p>Here's a sample documentation file to get you started:</p>
<div class="codehilite"><pre><span class="gh">Installation</span>
<span class="gh">============</span>

Here's how to install my project.

If you just want to see how to use it, take a look at the [samples][] page.

[samples]: /samples/

[TOC]

<span class="gh">Linux</span>
<span class="gh">-----</span>

Use your package manager.

<span class="gh">Windows</span>
<span class="gh">-------</span>

It depends on what version of Windows you have.

### Windows XP

<span class="cp">...</span>

### Windows Vista

<span class="cp">...</span>

### Windows 7

<span class="cp">...</span>
</pre></div>
            <footer><p>Created by <a href="http://stevelosh.com">Steve Losh</a>.  Inspired by <a href="http://stevelosh.com/projects/t/">t</a>.</p>
<script type="text/javascript">
    var _gauges = _gauges || [];
    (function() {
        var t   = document.createElement('script');
        t.type  = 'text/javascript';
        t.async = true;
        t.id    = 'gauges-tracker';
        t.setAttribute('data-site-id', '4f1df6cb844d521f7b000003');
        t.src = '//secure.gaug.es/track.js';
        var s = document.getElementsByTagName('script')[0];
        s.parentNode.insertBefore(t, s);
    })();
</script></footer></div>
    </body></html>
author	Steve Losh <steve@stevelosh.com>
date	Mon, 23 Jan 2012 19:38:19 -0500
parents	c9e5e7f76b20
children	(none)