chancery: Update site.
| author |
Steve Losh <steve@stevelosh.com> |
| date |
Mon, 23 Dec 2019 16:18:40 -0500 |
| parents |
80ebae4e1e52 |
| children |
(none) |
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8"/>
<title>FAQs / d</title>
<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>
<div class="markdown">
<h1 id="faqs"><a href="">FAQs</a></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="#what-if-i-outgrow-d">What if I Outgrow d?</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 <base> 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 <head> of the docs?</a></li>
</ul>
</li>
<li><a href="#writing-tools">Writing Tools</a><ul>
<li><a href="#how-can-i-preview-the-documentation-locally">How can I preview the documentation locally?</a></li>
<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="#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>
<li><a href="#can-i-make-a-theme-for-d">Can I make a "theme" for d?</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: <strong>no</strong>.</p>
<p>If you want to hook in API docs and such: <strong>no</strong>.</p>
<p>If you want to write in something other than Markdown: <strong>no</strong>.</p>
<p>If you have a large project and need more than one level of organization for
your documentation: <strong>no</strong>.</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="what-if-i-outgrow-d">What if I Outgrow d?</h2>
<p>If your documentation starts to need some more structure or functionality, you
can easily switch over to <a href="http://sphinx.pocoo.org/">Sphinx</a> in a few minutes:</p>
<ol>
<li>Use <a href="http://johnmacfarlane.net/pandoc/">Pandoc</a> to convert your Markdown to reStructuredText. There's
a <a href="http://johnmacfarlane.net/pandoc/try">web-based version</a> if you don't want to bother building
Haskell.</li>
<li>Create a new Sphinx project in the usual manner.</li>
<li>Copy your converted documentation into it.</li>
<li>That's it.</li>
</ol>
<p>There's nothing tricky about this process because <code>d</code> has almost no
process/configuration of its own. All you do when using <code>d</code> is create pure
content. This makes switching to other tools simple a matter of converting this
content to their preferred format.</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/><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="p">.</span>
<span class="p">[</span><span class="n">ig</span><span class="p">]</span><span class="o">:</span> <span class="p">..</span><span class="o">/</span><span class="n">installation</span><span class="o">/</span>
</pre></div>
<h3 id="why-cant-i-use-base62-to-have-normal-looking-links">Why can't I use <base> to have normal-looking links?</h3>
<p>The <code><base></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><span/>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><span/>:::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 <head> of the docs?</h3>
<p>Not yet, but it's on my radar.</p>
<h2 id="writing-tools">Writing Tools</h2>
<h3 id="how-can-i-preview-the-documentation-locally">How can I preview the documentation locally?</h3>
<p>You need a real web server to preview the generated files effectively. Luckily,
you already have one: Python comes with a built-in server that's great for
viewing local files.</p>
<p>Build your docs, then in a separate terminal:</p>
<div class="codehilite"><pre><span/><span class="nb">cd</span> myproject/docs
<span class="nb">cd</span> build
python -m SimpleHTTPServer
</pre></div>
<p>Now open <a href="http://localhost:8000">http://localhost:8000</a> and view your docs!</p>
<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/sjl/peat">peat</a> to watch for changes and run <code>d</code>.</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>
<h3 id="can-i-make-a-theme-for-d">Can I make a "theme" for d?</h3>
<p>No, use a different tool.</p>
</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>
<p><br/><a id="rochester-made" href="https://rochestermade.com" title="Rochester Made"><img src="http://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
</div>
</body>
</html>