6d25e2bfb2fe

d: Update site.
[view raw] [browse files]
author Steve Losh <steve@stevelosh.com>
date Mon, 23 Jan 2012 19:38:19 -0500
parents c9e5e7f76b20
children c2ccda2aa728
branches/tags (none)
files d/01-installation.markdown d/02-usage.markdown d/03-customization.markdown d/04-faqs.markdown d/base d/footer.markdown d/index.markdown d/publish.sh d/title

Changes

--- a/d/01-installation.markdown	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,14 +0,0 @@
-Installation
-============
-
-You just need Python and `pip`:
-
-    :::bash
-    pip install d
-
-You can use `easy_install` if you really want:
-
-    :::bash
-    easy_install d
-
-`d` uses Markdown, Pygments, and Pyquery to do some of the heavy lifting.
--- a/d/02-usage.markdown	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,135 +0,0 @@
-Usage
-=====
-
-`d` is designed to be easy and intuitive to use.  Here's a whirlwind tour that
-will get you up and running in five minutes.
-
-[TOC]
-
-Basic Flow
-----------
-
-Make a directory for your docs:
-
-    :::bash
-    mkdir docs
-    cd docs
-
-Write some docs:
-
-    :::bash
-    touch index.markdown
-    touch installation.markdown
-    touch usage.markdown
-
-    vim .
-
-Render your docs:
-
-    :::bash
-    d
-
-Copy the output somewhere:
-
-    :::bash
-    rsync -d build/ myserver:/var/www/myproject
-
-The Introduction Page
----------------------
-
-The text of the main page (above the table of contents) comes from the
-`index.markdown` file.
-
-This page doesn't need a title.  Just write out the text you want to show above
-the table of contents.
-
-The Footer
-----------
-
-The contents of the footer comes from `footer.markdown`.
-
-Documentation Files
--------------------
-
-There are a few rules to follow when writing docs for use with `d`.  They should
-be pretty intuitive once you try them out.
-
-### Extensions
-
-You can use `.markdown`, `.mdown`, or `.md` as the extension for your Markdown
-files.  `d` doesn't care.
-
-### Layout
-
-Each Markdown file (other than the introduction and footer) is rendered as
-a separate page.
-
-### Page Titles
-
-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.
-
-### Other Headings
-
-There shouldn't be any other level 1 headings.  Levels 2/3/4/5/6 are fine.
-
-### Links
-
-Link to other documents by using their filenames with no extension.
-
-For example: the URL for `usage.markdown` would be `/usage/`.
-
-### Relative URLs
-
-If you're planning on serving these docs at a URL other than `/` you should add
-`..` before links to other pages.
-
-For example: the URL for `usage.markdown` would now be `../usage/`.
-
-**Note:** these relative URLs are safe to use even when you're serving the docs
-at `/`, so there's no disadvantage to using them other than a bit more typing.
-
-### Tables of Contents
-
-Use `[TOC]` to display a table of contents for the current page, if you want
-one.
-
-Example
--------
-
-Here's a sample documentation file to get you started:
-
-    :::markdown
-    Installation
-    ============
-
-    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]
-
-    Linux
-    -----
-
-    Use your package manager.
-
-    Windows
-    -------
-
-    It depends on what version of Windows you have.
-
-    ### Windows XP
-
-    ...
-
-    ### Windows Vista
-
-    ...
-
-    ### Windows 7
-
-    ...
-
--- a/d/03-customization.markdown	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,36 +0,0 @@
-Customization
-=============
-
-`d` is mostly designed for quick and dirty use.  There are a few customization
-options, but if you find yourself wanting more you probably need a different
-tool.
-
-[TOC]
-
-Project Title
--------------
-
-`d` tries to intelligently guess your project's title.  You can override it by
-creating a `title` file with the title inside.
-
-Page Titles
------------
-
-`d` takes page titles from the first line of the file, which should be a level
-1 Markdown heading.
-
-Page URLs
----------
-
-The URL for each page will be the filename of the page, without an extension.
-For example, `usage.markdown` will have a URL of `/usage/`.
-
-There is one exception: if a filename starts with a number and a dash, `d` will
-ignore those for the URLs (but will sort on them, so you can use this to reorder
-pages).
-
-Footer
-------
-
-The contents of the footer are rendered from `footer.markdown`, or left blank if
-you don't have it.
--- a/d/04-faqs.markdown	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,129 +0,0 @@
-FAQs
-====
-
-Maybe not "frequently asked", but hopefully these answers will be useful.
-
-[TOC]
-
-Should I use d for my project?
-------------------------------
-
-If you want lots of control over the resulting documentation: no.
-
-If you want to hook in API docs and such: no.
-
-If you want to write in something other than Markdown: no.
-
-If you have a large project and need more than one level of organization for
-your documentation: no.
-
-If you have a small project and want to quickly write some docs that don't look
-like ass: **yes!**
-
-Web Servers and File Layout
----------------------------
-
-### Do I need to do anything special with my webserver?
-
-Your webserver should add a trailing slash to directories.  Most sane ones do
-that by default these days, so you should be all set.
-
-If you're using a server that doesn't, you might need to add a rewrite rule so
-URLs like `/foo` redirect to `/foo/`.
-
-### Why does d use page/index.html instead of page.html?
-
-`d`'s goal is to be quick, easy, and get out of your way.  Most web servers will
-serve the folder structure `d` creates sanely without any extra configuration.
-
-This also lets you type links such as `[installation guide](/installation/)`,
-instead of requiring you to add the `.html`.
-
-### Can I serve the documentation at a URL other than /?
-
-Sure.  You'll need to use relative links in your content pages though:
-
-    :::markdown
-    See the [installation guide][ig] for more information.
-
-    [ig]: ../installation/
-
-
-### Why can't I use <base\> to have normal-looking links?
-
-The `<base>` tag is a clusterfuck.  Just add the dots.  Trust me.
-
-### Can I reorder the pages?
-
-Sure, make the filenames start with numbers and a dash, like this:
-
-    :::text 
-    01-installation.markdown
-    02-usage.markdown
-
-`d` will order the files properly, but ignore the number when creating the
-URLs, so you still get nice links like `/installation/`.
-
-### Can I create multiple folders/sections?
-
-No, use a different tool.
-
-Page Content
-------------
-
-### Can I add a Google Analytics script?
-
-Sure.  Remember that Markdown lets you add raw HTML anywhere.  Just put the HTML
-in `footer.markdown` and you're all set.
-
-### Can I add media?
-
-Not yet, but it's on my radar.
-
-### Can I display a table of contents for a single page?
-
-Put `[TOC]` 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.
-
-### Can I have syntax highlighting for code snippets?
-
-Yep, just put `:::lang` at the beginning of your code blocks, like this:
-
-    :::text
-    :::python
-    for i in range(10):
-        print i
-
-### Can I add HTML into the <head\> of the docs?
-
-Not yet, but it's on my radar.
-
-
-Writing Tools
--------------
-
-### Can I make d auto-rerender when my files change?
-
-Yes, use [kicker](https://github.com/alloy/kicker) to watch for changes and run
-`d`.
-
-### Kicker is only for OS X, what about Linux?
-
-I haven't found a tool like kicker for Linux, sorry.
-
-Let me know if you write one -- I've wanted it for a while now.
-
-### Can I write in something other than Markdown?
-
-No, use a different tool.
-
-### Can I add auto-generated documentation into d's docs?
-
-No, auto-generated docs are a cop out.  Sit down and write some real,
-hand-crafted documentation for humans.
-
-### Can I output to PDF/ePub/man pages/etc?
-
-No, use a different tool.
-
--- a/d/base	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-/build/
--- a/d/footer.markdown	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,15 +0,0 @@
-Created by [Steve Losh](http://stevelosh.com).  Inspired by [t](http://stevelosh.com/projects/t/).
-
-<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>
--- a/d/index.markdown	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,18 +0,0 @@
-<img style="border: 6px solid #ddd; height: 300px; float: right; padding: 1px; background: #aaa; margin-left: 20px;"
-     src="http://i.imgur.com/JFzdX.png" title="Documentation without the hair-tearing." alt="Comic"/>
-
-You need to write documentation.  `d` makes it easy:
-
-* Put a bunch of Markdown files in a directory.
-* Run `d`.
-* Get on with your life.
-
-No fiddling around with configuration files, themes, version numbers,
-obtuse markup, or multiple output formats.
-
-Make some Markdown files.  Run `d`.  Move on.
-
-`d` is open source on [BitBucket][] and [GitHub][].  It's MIT/X11 licensed.
-
-[BitBucket]: http://bitbucket.org/sjl/d
-[GitHub]: http://github.com/sjl/d
--- a/d/publish.sh	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,7 +0,0 @@
-#!/usr/bin/env bash
-
-~/lib/virtualenvs/d/bin/python ../bin/d
-hg -R ~/src/sjl.bitbucket.org pull -u
-rsync --delete -az . ~/src/sjl.bitbucket.org/d
-hg -R ~/src/sjl.bitbucket.org commit -Am 'd: Update site.'
-hg -R ~/src/sjl.bitbucket.org push
--- a/d/title	Mon Jan 23 19:34:25 2012 -0500
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,1 +0,0 @@
-d