hg.stevelosh.com > docs.stevelosh.com

<html><head><title>FAQs / 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="faqs">FAQs</h1>
<p>Maybe not "frequently asked", but hopefully these answers will be useful.</p>
<div class="toc">
<ul><li><a href="#should-i-use-d-for-my-project">Should I use d for my project?</a></li>
<li><a href="#web-servers-and-file-layout">Web Servers and File Layout</a><ul><li><a href="#do-i-need-to-do-anything-special-with-my-webserver">Do I need to do anything special with my webserver?</a></li>
<li><a href="#why-does-d-use-pageindexhtml-instead-of-pagehtml">Why does d use page/index.html instead of page.html?</a></li>
<li><a href="#can-i-serve-the-documentation-at-a-url-other-than">Can I serve the documentation at a URL other than /?</a></li>
<li><a href="#why-cant-i-use-base62-to-have-normal-looking-links">Why can't I use &lt;base&gt; to have normal-looking links?</a></li>
<li><a href="#can-i-reorder-the-pages">Can I reorder the pages?</a></li>
<li><a href="#can-i-create-multiple-folderssections">Can I create multiple folders/sections?</a></li>
</ul></li>
<li><a href="#page-content">Page Content</a><ul><li><a href="#can-i-add-a-google-analytics-script">Can I add a Google Analytics script?</a></li>
<li><a href="#can-i-add-media">Can I add media?</a></li>
<li><a href="#can-i-display-a-table-of-contents-for-a-single-page">Can I display a table of contents for a single page?</a></li>
<li><a href="#can-i-have-syntax-highlighting-for-code-snippets">Can I have syntax highlighting for code snippets?</a></li>
<li><a href="#can-i-add-html-into-the-head62-of-the-docs">Can I add HTML into the &lt;head&gt; of the docs?</a></li>
</ul></li>
<li><a href="#writing-tools">Writing Tools</a><ul><li><a href="#can-i-make-d-auto-rerender-when-my-files-change">Can I make d auto-rerender when my files change?</a></li>
<li><a href="#kicker-is-only-for-os-x-what-about-linux">Kicker is only for OS X, what about Linux?</a></li>
<li><a href="#can-i-write-in-something-other-than-markdown">Can I write in something other than Markdown?</a></li>
<li><a href="#can-i-add-auto-generated-documentation-into-ds-docs">Can I add auto-generated documentation into d's docs?</a></li>
<li><a href="#can-i-output-to-pdfepubman-pagesetc">Can I output to PDF/ePub/man pages/etc?</a></li>
</ul></li>
</ul></div>
<h2 id="should-i-use-d-for-my-project">Should I use d for my project?</h2>
<p>If you want lots of control over the resulting documentation: no.</p>
<p>If you want to hook in API docs and such: no.</p>
<p>If you want to write in something other than Markdown: no.</p>
<p>If you have a large project and need more than one level of organization for
your documentation: no.</p>
<p>If you have a small project and want to quickly write some docs that don't look
like ass: <strong>yes!</strong></p>
<h2 id="web-servers-and-file-layout">Web Servers and File Layout</h2>
<h3 id="do-i-need-to-do-anything-special-with-my-webserver">Do I need to do anything special with my webserver?</h3>
<p>Your webserver should add a trailing slash to directories.  Most sane ones do
that by default these days, so you should be all set.</p>
<p>If you're using a server that doesn't, you might need to add a rewrite rule so
URLs like <code>/foo</code> redirect to <code>/foo/</code>.</p>
<h3 id="why-does-d-use-pageindexhtml-instead-of-pagehtml">Why does d use page/index.html instead of page.html?</h3>
<p><code>d</code>'s goal is to be quick, easy, and get out of your way.  Most web servers will
serve the folder structure <code>d</code> creates sanely without any extra configuration.</p>
<p>This also lets you type links such as <code>[installation guide](/installation/)</code>,
instead of requiring you to add the <code>.html</code>.</p>
<h3 id="can-i-serve-the-documentation-at-a-url-other-than">Can I serve the documentation at a URL other than /?</h3>
<p>Sure.  You'll need to use relative links in your content pages though:</p>
<div class="codehilite"><pre><span class="n">See</span> <span class="n">the</span> <span class="p">[</span><span class="n">installation</span> <span class="n">guide</span><span class="p">][</span><span class="n">ig</span><span class="p">]</span> <span class="k">for</span> <span class="n">more</span> <span class="n">information</span><span class="o">.</span>

<span class="p">[</span><span class="n">ig</span><span class="p">]:</span> <span class="o">..</span><span class="sr">/installation/</span>
</pre></div>


<h3 id="why-cant-i-use-base62-to-have-normal-looking-links">Why can't I use &lt;base&gt; to have normal-looking links?</h3>
<p>The <code>&lt;base&gt;</code> tag is a clusterfuck.  Just add the dots.  Trust me.</p>
<h3 id="can-i-reorder-the-pages">Can I reorder the pages?</h3>
<p>Sure, make the filenames start with numbers and a dash, like this:</p>
<div class="codehilite"><pre>01-installation.markdown
02-usage.markdown
</pre></div>


<p><code>d</code> will order the files properly, but ignore the number when creating the
URLs, so you still get nice links like <code>/installation/</code>.</p>
<h3 id="can-i-create-multiple-folderssections">Can I create multiple folders/sections?</h3>
<p>No, use a different tool.</p>
<h2 id="page-content">Page Content</h2>
<h3 id="can-i-add-a-google-analytics-script">Can I add a Google Analytics script?</h3>
<p>Sure.  Remember that Markdown lets you add raw HTML anywhere.  Just put the HTML
in <code>footer.markdown</code> and you're all set.</p>
<h3 id="can-i-add-media">Can I add media?</h3>
<p>Not yet, but it's on my radar.</p>
<h3 id="can-i-display-a-table-of-contents-for-a-single-page">Can I display a table of contents for a single page?</h3>
<p>Put <code>[TOC]</code> wherever you want it to appear.  It will parse the headings in the
document, remove the first level (the page title) and output a nice list for
you.</p>
<h3 id="can-i-have-syntax-highlighting-for-code-snippets">Can I have syntax highlighting for code snippets?</h3>
<p>Yep, just put <code>:::lang</code> at the beginning of your code blocks, like this:</p>
<div class="codehilite"><pre>:::python
for i in range(10):
    print i
</pre></div>


<h3 id="can-i-add-html-into-the-head62-of-the-docs">Can I add HTML into the &lt;head&gt; of the docs?</h3>
<p>Not yet, but it's on my radar.</p>
<h2 id="writing-tools">Writing Tools</h2>
<h3 id="can-i-make-d-auto-rerender-when-my-files-change">Can I make d auto-rerender when my files change?</h3>
<p>Yes, use <a href="https://github.com/alloy/kicker">kicker</a> to watch for changes and run
<code>d</code>.</p>
<h3 id="kicker-is-only-for-os-x-what-about-linux">Kicker is only for OS X, what about Linux?</h3>
<p>I haven't found a tool like kicker for Linux, sorry.</p>
<p>Let me know if you write one -- I've wanted it for a while now.</p>
<h3 id="can-i-write-in-something-other-than-markdown">Can I write in something other than Markdown?</h3>
<p>No, use a different tool.</p>
<h3 id="can-i-add-auto-generated-documentation-into-ds-docs">Can I add auto-generated documentation into d's docs?</h3>
<p>No, auto-generated docs are a cop out.  Sit down and write some real,
hand-crafted documentation for humans.</p>
<h3 id="can-i-output-to-pdfepubman-pagesetc">Can I output to PDF/ePub/man pages/etc?</h3>
<p>No, use a different tool.</p>
            <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:34:25 -0500
parents	(none)
children	(none)