Imported Upstream version 4.0.3upstream/4.0.3

2 files changed, 1044 insertions, 0 deletions

diff --git a/docs/manual.txt b/docs/manual.txt
new file mode 100644
index 0000000..f8804e6
--- /dev/null
+++ b/docs/manual.txt
@@ -0,0 +1,808 @@
+The Nikola Handbook
+===================
+
+:Version: 2.1+svn
+:Author: Roberto Alsina <ralsina@netmanagers.com.ar>
+
+.. class:: alert alert-info pull-right
+
+.. contents::
+
+
+All You Need to Know
+--------------------
+
+After you have Nikola installed:
+
+Create a site:
+    ``nikola init mysite``
+
+Create a post:
+    ``doit new_post``
+
+Edit the post:
+    The filename should be in the output of the previous command.
+
+Build the site:
+     ``doit``
+
+Start the test server:
+     ``doit serve``
+
+See the site:
+     http://127.0.0.1:8000
+
+That should get you going. If you want to know more, this manual will always be here
+for you.
+
+DON'T READ THIS MANUAL. IF YOU NEED TO READ IT I FAILED, JUST USE THE THING.
+
+On the other hand, if anything about Nikola is not as obvious as it should be, by all
+means tell me about it :-)
+
+What's Nikola and what can you do with it?
+------------------------------------------
+
+Nikola is a static website and blog generator. The very short explanation is
+that it takes some texts you wrote, and uses them to create a folder full
+of HTML files. If you upload that folder to a server, you will have a
+rather full-featured website, done with little effort.
+
+It's original goal is to create blogs, but it supports most kind of sites, and
+can be used as a CMS, as long as what you present to the user is your own content
+instead of something the user generates.
+
+Nikola can do:
+
+* A blog (`example <http://lateral.netmanagers.com.ar>`__)
+* Your company's site
+* Your personal site
+* A software project's site (`example <http://nikola.ralsina.com.ar>`__)
+* A book's site
+
+Since Nikola-based sites don't run any code on the server, there is no way to process
+user input in forms.
+
+Nikola can't do:
+
+* Twitter
+* Facebook
+* An Issue tracker
+* Anything with forms, really (except for comments_!)
+
+Keep in mind that "static" doesn't mean **boring**. You can have animations, slides
+or whatever fancy CSS/HTML5 thingie you like. It only means all that HTML is
+generated already before being uploaded. On the other hand, Nikola sites will
+tend to be content-heavy. What Nikola is good at is at putting what you write
+out there.
+
+Getting Help
+------------
+
+* Feel free to contact me at ralsina@netmanagers.com.ar for questions about Nikola.
+* You can file bugs at `the issue tracker <http://code.google.com/p/nikola-generator/issues/list>`__
+* You can discuss Nikola at the `nikola-discuss google group <http://groups.google.com/group/nikola-discuss>`_
+* You can subscribe to `the Nikola Blog <http://nikola.ralsina.com.ar/blog>`_
+* You can follow `Nikola on Twitter <https://twitter.com/#!/nikolagenerator>`_
+
+Why Static?
+-----------
+
+Most "modern" websites are *dynamic* in the sense that the contents of the site
+live in a database, and are converted into presentation-ready HTML only when a
+user wants to see the page. That's great. However, it presents some minor issues
+that static site generators try to solve.
+
+In a static site, the whole site, every page, *everything*, is created before
+the first user even sees it and uploaded to the server as a simple folder full
+of HTML files (and images, CSS, etc).
+
+So, let's see some reasons for using static sites:
+
+Security
+    Dynamic sites are prone to experience security issues. The solution for that
+    is constant vigilance, keeping the software behind the site updated, and
+    plain old good luck. The stack of software used to provide a static site,
+    like those Nikola generates, is much smaller (Just a webserver).
+
+    A smaller software stack implies less security risk.
+
+Obsolescense
+    If you create a site using (for example) Wordpress, what happens when Wordpress
+    releases a new version? You have to update your Wordpress. That is not optional,
+    because of security and support issues. If I release a new version of Nikola, and
+    you don't update, *nothing* happens. You can continue to use the version you
+    have now forever, no problems.
+
+    Also, in the longer term, the very foundations of dynamic sites shift. Can you
+    still deploy a blog software based on Django 0.96? What happens when your
+    host stops supporting the php version you rely on? And so on.
+
+    You may say those are long term issues, or that they won't matter for years. Well,
+    I believe things should work forever, or as close to it as we can make them.
+    Nikola's static output and its input files will work as long as you can install
+    a Python > 2.5 (soon 3.x) in a Linux, Windows, or Mac and can find a server
+    that sends files over HTTP. That's probably 10 or 15 years at least.
+
+    Also, static sites are easily handled by the Internet Archive.
+
+Cost and Performance
+    On dynamic sites, every time a reader wants a page, a whole lot of database
+    queries are made. Then a whole pile of code chews that data, and HTML is
+    produced, which is sent to the user. All that requires CPU and memory.
+
+    On a static site, the highly optimized HTTP server reads the file from disk
+    (or, if it's a popular file, from disk cache), and sends it to the user. You could
+    probably serve a bazillion (technical term) pageviews from a phone using
+    static sites.
+
+Lockin
+    On server-side blog platforms, sometimes you can't export your own data, or
+    it's in strange formats you can't use in other services. I have switched
+    blogging platforms from Advogato to PyCs to two homebrewed systems, to Nikola,
+    and have never lost a file, a URL, or a comment. That's because I have *always*
+    had my own data in a format of my choice.
+
+    With Nikola, you own your files, and you can do anything with them.
+
+Features
+--------
+
+Nikola has a very defined featureset: it has every feature I needed for my own sites.
+Hopefully, it will be enough for others, and anyway, I am open to suggestions.
+
+If you want to create a blog or a site, Nikola provides:
+
+* Front page (and older posts pages)
+* RSS Feeds
+* Pages and feeds for each tag you used
+* Custom search
+* Full yearly archives
+* Custom output paths for generated pages
+* Easy page template customization
+* Static pages (not part of the blog)
+* Internationalization support (my own blog is English/Spanish)
+* Google sitemap generation
+* Custom deployment (if it's a command, you can use it)
+* A (very) basic look and feel you can customize, and is even text-mode friendly
+* The input format is light markup (`reStructuredText <quickstart.html>`_ or
+  `Markdown <http://daringfireball.net/projects/markdown/>`_)
+* Easy-to-create image galleries
+
+Also:
+
+* A preview webserver
+* "Live" re-rendering while you edit
+* "Smart" builds: only what changed gets rebuilt (usually in 1 or 2 seconds)
+* Very easy to extend with minimal Python knowledge.
+
+Installing Nikola
+-----------------
+
+This is currently lacking on detail. Considering the niche Nikola is aimed at,
+I suspect that's not a problem yet. So, when I say "get", the specific details
+of how to "get" something for your specific operating system are left to you.
+
+The short version is: ``pip install https://github.com/ralsina/nikola/zipball/master``
+
+Longer version:
+
+#. Get python, if you don't have it.
+#. Get `doit <http://python-doit.sf.net>`_
+#. Get `docutils <http://docutils.sf.net>`_
+#. Get `Mako <http://makotemplates.org>`_
+#. Get `PIL <http://www.pythonware.com/products/pil/>`_
+#. Get `Pygments <http://pygments.org/>`_
+#. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_
+#. Get `lxml <http://lxml.de/>`_
+
+Any non-prehistorical version of the above should work, and if you are in Linux
+you can try to use your distribution's packages if they exist, but the newer the better.
+
+Then get Nikola itself (<http://nikola.ralsina.com.ar/>), unzip it, and
+run ``python setup.py install``.
+
+After that, run ``nikola init sitename`` and that will create a folder called
+``sitename`` containing a functional demo site.
+
+Getting Started
+---------------
+
+To create posts and pages in Nikola, you write them in restructured text or Markdown, light
+markups that are later converted to HTML (I may add support for textile or other
+markups later). There is a great `quick tutorial to learn restructured text. <quickstart.html>`_
+
+First, let's see how you "build" your site. Nikola comes with a minimal site to get you started.
+
+The tool used to do builds is called `doit <http://python-doit.sf.net>`_, and it rebuilds the
+files that are not up to date, so your site always reflects your latest content. To do our
+first build, just run "doit"::
+
+    $ doit
+    Parsing metadata
+    .  render_posts:stories/manual.html
+    .  render_posts:posts/1.html
+    .  render_posts:stories/1.html
+    .  render_archive:output/2012/index.html
+    .  render_archive:output/archive.html
+    .  render_indexes:output/index.html
+    .  render_pages:output/posts/welcome-to-nikola.html
+    .  render_pages:output/stories/about-nikola.html
+    .  render_pages:output/stories/handbook.html
+    .  render_rss:output/rss.xml
+    .  render_sources:output/stories/about-nikola.txt
+    :
+    :
+    :
+
+Nikola will print a line for every output file it generates. If we do it again, that
+will be much much shorter::
+
+    $ doit
+    Parsing metadata
+    .  sitemap
+
+That is because `doit <http://python-doit.sf.net>`_ is smart enough not to generate
+all the pages again, unless you changed something that the page requires. So, if you change
+the text of a post, or its title, that post page, and all index pages where it is mentioned,
+will be recreated. If you change the post page template, then all the post pages will be rebuilt.
+
+Nikola is a series of doit *tasks*, and you can see them by doing ``doit list``::
+
+    $ doit list
+    Scanning posts  . . done!
+    copy_assets        Create tasks to copy the assets of the whole theme chain.
+    copy_files         Copy static files into the output folder.
+    deploy             Deploy site.
+    new_page           Create a new post (interactive).
+    new_post           Create a new post (interactive).
+    redirect           Generate redirections.
+    render_archive     Render the post archives.
+    render_galleries   Render image galleries.
+    render_indexes     Render 10-post-per-page indexes.
+    render_pages       Build final pages from metadata and HTML fragments.
+    render_posts       Build HTML fragments from metadata and reSt.
+    render_rss         Generate RSS feeds.
+    render_site        Render the post archives.
+    render_sources     Publish the rst sources because why not?
+    render_tags        Render the tag pages.
+    serve              Start test server. (Usage: doit serve [--address 127.0.0.1] [--port 8000])
+    sitemap            Generate Google sitemap.
+
+You can make Nikola redo everything by calling ``doit clean``, you can make it do just a specific
+part of the site using task names, for example ``doit render_pages``, and even individual files like
+``doit render_indexes:output/index.html``
+
+The ``serve`` task is special, in that instead of generating a file it starts a web server so
+you can see the site you are creating::
+
+    $ doit serve
+    Parsing metadata
+    .  serve
+    Serving HTTP on 127.0.0.1 port 8000 ...
+
+After you do this, you can point your web browser to http://localhost:8000 and you should see
+the sample site. This is useful as a "preview" of your work. You can combine add ``auto`` and do
+``doit auto serve`` which makes doit automatically regenerate your pages as needed, and
+it's a live preview!
+
+By default, the ``serve`` task runs the web server on port 8000 on the IP address 127.0.0.1.
+You can pass in an IP address and port number explicity using ``-a IP_ADDRESS``
+(short version of ``--address``) or ``-p PORT_NUMBER`` (short version of ``--port``)
+Example usage::
+
+    $ doit serve --address 0.0.0.0 --port 8080
+    Parsing metadata
+    .  serve
+    Serving HTTP on 0.0.0.0 port 8080 ...
+
+The ``deploy`` task is discussed in the Deployment_ section.
+
+Creating a Blog Post
+--------------------
+
+A post consists of two files, a metadata file (``post-title.meta``) and a
+file containing the contents written in  `restructured text <http://docutils.sf.net>`_
+(``post-title.txt``), markdown or HTML. Which input type is used is guessed using
+the ``post_compilers`` option in ``conf.py`` but by default, the extensions
+supported are:
+
+.txt .rst
+    Restructured Text
+
+.md .markdown .mdown
+    Markdown
+
+.htm .html
+    HTML
+
+The default configuration expects them to be placed in ``posts`` but that can be
+changed (see below, the post_pages option)
+
+You can just create them in ``posts`` or use a little helper task provided by Nikola::
+
+    $ doit new_post
+    Parsing metadata
+    .  new_post
+    Creating New Post
+    -----------------
+
+    Enter title: How to Make Money
+    Your post's metadata is at:  posts/how-to-make-money.meta
+    Your post's text is at:  posts/how-to-make-money.txt
+
+The format for the ``.meta`` file is as follows::
+
+    How to Make Money
+    how-to-make-money
+    2012/04/09 13:59
+
+The first line is the title. The second one is the pagename. Since often titles will have
+characters that look bad on URLs, it's generated as a "clean" version of the title.
+The third line is the post's date, and is set to "now".
+
+You can add three more optional lines. A fourth line that is a list of tags
+separated with commas (spaces around the commas are ignored)::
+
+    programming, python, fame, fortune
+
+And a fifth line that's a URL for an original source of the post.
+
+And a sixth line that's the page description.
+
+If you are writing a multilingual site, you can also create a per-language
+metadata file. This one can have two lines:
+
+1) The translated title for the post or page
+2) A translated version of the pagename
+
+You can edit these files with your favourite text editor, and once you are happy
+with the contents, generate the pages as explained in `Getting Started`_
+
+Currently supported languages are
+
+* English
+* Spanish
+* French
+* German
+* Russian
+* Greek.
+
+If you wish to add support for more languages, check out the instructions
+at the `theming guide <http://nikola.ralsina.com.ar/theming.html>`.
+
+The post page is generated using the ``post.tmpl`` template, which you can use
+to customize the output.
+
+The place where the post will be placed by ``new_post`` is based on the ``post_pages``
+configuration option::
+
+    # post_pages contains (wildcard, destination, template, use_in_feed) tuples.
+    #
+    # The wildcard is used to generate a list of reSt source files (whatever/thing.txt)
+    # That fragment must have an associated metadata file (whatever/thing.meta),
+    # and opcionally translated files (example for spanish, with code "es"):
+    #     whatever/thing.txt.es and whatever/thing.meta.es
+    #
+    # From those files, a set of HTML fragment files will be generated:
+    # cache/whatever/thing.html (and maybe cache/whatever/thing.html.es)
+    #
+    # These files are combinated with the template to produce rendered
+    # pages, which will be placed at
+    # output / TRANSLATIONS[lang] / destination / pagename.html
+    #
+    # where "pagename" is specified in the metadata file.
+    #
+    # if use_in_feed is True, then those posts will be added to the site's
+    # rss feeds.
+    #
+    post_pages = (
+        ("posts/*.txt", "posts", "post.tmpl", True),
+        ("stories/*.txt", "stories", "story.tmpl", False),
+    )
+
+It will use the first location that has the last parameter set to True, or the last
+one in the list if all of them have it set to False.
+
+Alternatively, you can not have a meta file and embed the metadata in the post itself.
+
+In restructured text::
+
+    .. tags: test,demo
+    .. slug: demo-test
+    .. date: 2012/04/09 13:59
+    .. link: http://foo.bar/baz
+
+In Markdown:
+    <!--
+    .. tags: test,demo
+    .. slug: demo-test
+    .. date: 2012/04/09 13:59
+    .. link: http://foo.bar/baz
+    -->
+
+Teasers
+~~~~~~~
+
+If for any reason you want to provide feeds that only display the beginning of
+your post, you only need to add a "magical comment" in your post.
+
+In restructuredtext::
+
+   .. TEASER_END
+
+In Markdown::
+
+   <!-- TEASER_END -->
+
+Additionally, if you want also the "index" pages to show only the teasers, you can
+set the variable ``INDEX_TEASERS`` to ``True`` in ``conf.py``.
+
+Drafts
+~~~~~~
+
+If you add a "draft" tag to a post, then it will not be shown in indexes and feeds.
+It *will* be compiled, and if you deploy it it *will* be made available, so use
+with care.
+
+
+Creating a Page
+---------------
+
+Pages are the same as posts, except that:
+
+* They are not added to the front page
+* They don't appear on the RSS feed
+* They use the ``story.tmpl`` template instead of ``post.tmpl`` by default
+
+The default configuration expects the page's metadata and text files to be on the
+``stories`` folder, but that can be changed (see post_pages option above).
+
+You can create the page's files manually or use the helper ``new_page`` that works exactly like
+the ``new_post`` described above, except it will place the files in the folder that
+has ``use_in_feed`` set to False.
+
+Redirections
+------------
+
+If you need a page to be available in more than one place, you can define redirections
+in your ``conf.py``::
+
+    # A list of redirection tuples, [("foo/from.html", "/bar/to.html")].
+    #
+    # A HTML file will be created in output/foo/from.html that redirects
+    # to the "/bar/to.html" URL. notice that the "from" side MUST be a
+    # relative URL.
+    #
+    # If you don't need any of these, just set to []
+
+    REDIRECTIONS = [("index.html", "/weblog/index.html")]
+
+It's better if you can do these using your web server's configuration, but if
+you can't, this will work.
+
+Configuration
+-------------
+
+The configuration file is called ``conf.py`` and can be used to customize a lot of
+what Nikola does. Its syntax is python, but if you don't know the language, it
+still should not be terribly hard to grasp.
+
+The default ``conf.py`` you get with Nikola should be fairly complete, and is quite
+commented, but just in case, here is a full,
+`customized example configuration <sampleconfig.html>`_ (the one I use for
+`my site <http://lateral.netmanagers.com.ar>`_)
+
+Adding Files
+------------
+
+Any files you want to be in ``output/`` but are not generated by Nikola (for example,
+``favicon.ico``, just put it in ``files/``. Everything there is copied into
+``output`` by the ``copy_files`` task. Remember that you can't have files that collide
+with files Nikola generates (it will give an error).
+
+.. admonition:: Important
+
+   Don't put any files manually in ``output/``. Ever. Really. Maybe someday Nikola
+   will just wipe ``output/`` and then you will be sorry. So, please don't do that.
+
+If you want to copy more than one folder of static files into ``output`` you can
+change the FILES_FOLDERS option::
+
+    # One or more folders containing files to be copied as-is into the output.
+    # The format is a dictionary of "source" "relative destination".
+    # Default is:
+    # FILES_FOLDERS = {'files': '' }
+    # Which means copy 'files' into 'output'
+
+Post Processing Filters
+-----------------------
+
+You can apply post processing to the files in your site, in order to optimize them
+or change them in arbitrary ways. For example, you may want to compress all CSS
+and JS files using yui-compressor.
+
+To do that, you can use the provided helper adding this in your ``config.py``::
+
+  from nikola import filters
+
+  FILTERS = {
+    ".css": [filters.yui_compressor],
+    ".js": [filters.yui_compressor],
+  }
+
+Where ``filters.yui_compressor`` is a helper function provided by Nikola. You can
+replace that with strings describing command lines, or arbitrary python functions.
+
+If there's any specific thing you expect to be generally useful as a filter, contact
+me and I will add it to the filters library so that more people use it.
+
+Customizing Your Site
+---------------------
+
+There are lots of things you can do to persoalize your website, but let's see the easy ones!
+
+Basics
+    You can assume this needs to be changed::
+
+        # Data about this site
+        BLOG_TITLE = "Demo Site"
+        BLOG_URL = "http://nikola.ralsina.com.ar"
+        BLOG_EMAIL = "joe@demo.site"
+        BLOG_DESCRIPTION = "This is a demo site for Nikola."
+
+CSS tweaking
+    The default configuration includes a file, ``themes/default/assets/css/custom.css``
+    which is empty. Put your CSS there, for minimal disruption of the provided CSS files.
+
+    If you feel tempted to touch other files in assets, you probably will be better off
+    with a `custom theme <theming.html>`_.
+
+Template tweaking
+    If you really want to change the pages radically, you will want to do a
+    `custom theme <theming.html>`_.
+
+
+Sidebar
+    ``LICENSE`` is a HTML snippet for things like a CC badge, or whatever you prefer.
+
+    The 'sidebar_links' option lets you define what links go in the right-hand
+    sidebar, so you can link to important pages, or to other sites.
+
+    The ``SEARCH_FORM`` option contains the HTML code for a search form based on
+    duckduckgo.com which should always work, but feel free to change it to
+    something else.
+
+Footer
+    ``CONTENT_FOOTER`` is displayed, small at the bottom of all pages, I use it for
+    the copyright notice.
+
+Analytics
+    This is probably a misleading name, but the ``ANALYTICS`` option lets you define
+    a HTML snippet that will be added at the bottom of body. The main usage is
+    a Google analytics snippet or something similar, but you can really put anything
+    there.
+
+Getting More Themes
+-------------------
+
+There are not so many themes for Nikola. On occasion, I port something I like, and make
+it available for download. Nikola has a builtin theme download/install mechanism, its
+``install_theme`` task::
+
+    $ doit install_theme -l
+    Scanning posts  . . done!
+    .  install_theme
+    Themes:
+    -------
+    blogtxt
+    readable
+
+    $ doit install_theme -n blogtxt
+    Scanning posts  . . done!
+    .  install_theme
+    Downloading: http://nikola.ralsina.com.ar/themes/blogtxt.zip
+    Extracting: blogtxt into themes
+
+And there you are, you now have themes/blogtxt installed. It's very rudimentary, but it
+should work in most cases.
+
+If you create a nice theme, please share it! You can post about it on
+`the nikola forum <http://groups.google.com/group/nikola-discuss>`_ and I will
+make it available for download.
+
+One other option is to tweak an existing theme using a different color scheme,
+typography and CSS in general. Nikola provides a ``bootswatch_theme`` option
+to create a custom theme by downloading free CSS files from http://bootswatch.com::
+
+    $ doit bootswatch_theme -n custom_theme -s spruce -p site
+    Scanning posts  . . done!
+    .  bootswatch_theme
+    Creating custom_theme theme from spruce and site
+    Downloading:  http://bootswatch.com/spruce/bootstrap.min.css
+    Downloading:  http://bootswatch.com/spruce/bootstrap.css
+    Theme created. Change the THEME setting to "custom_theme" to use it.
+
+You can even try what different swatches do on an existing site using
+their handy `bootswatchlet <http://news.bootswatch.com/post/29555952123/a-bookmarklet-for-bootswatch>`_
+
+Play with it, there's cool stuff there. This feature was suggested by
+`clodo <http://elgalpondebanquito.com.ar>`_.
+
+Deployment
+----------
+
+Nikola doesn't really have a concept of deployment. However, if you can specify your
+deployment procedure as a series of commands, you can put them in the ``DEPLOY_COMMANDS``
+option, and run them with ``doit deploy``.
+
+One caveat is that if any command has a % in it, you should double them.
+
+Here is an example, from my own site's deployment script::
+
+    DEPLOY_COMMANDS = [
+        'rsync -rav --delete output/* ralsina@lateral.netmanagers.com.ar:/srv/www/lateral',
+        'rdiff-backup output ~/bartleblog-backup',
+        "links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar'",
+        'rsync -rav ~/bartleblog-backup/* ralsina@netmanagers.com.ar:bartleblog-backup',
+    ]
+
+Other interesting ideas are using
+`git as a deployment mechanism <http://toroid.org/ams/git-website-howto>`_ (or any other VCS
+for that matter), using `lftp mirror <http://lftp.yar.ru/>`_ or unison, or dropbox, or
+Ubuntu One. Any way you can think of to copy files from one place to another is good enough.
+
+Comments
+--------
+
+While Nikola creates static sites, there is a minimum level of user interaction you
+are probably expecting: comments.
+
+The default templates contain support for `Disqus <http://disqus.com>`_. All you have
+to do is register a forum, put its short name in the ``DISQUS_FORUM`` option.
+
+Disqus is a good option because:
+
+1) It doesn't require any server-side software on your site
+2) They offer you a way to export your comments, so you can take
+   them with you if you need to.
+3) It's free.
+4) It's damn nice.
+
+.. admonition:: Important
+
+   In some cases, when you run the test site, you won't see the comments.
+   That can be fixed by adding the disqus_developer flag to the templates
+   but it's probably more trouble than it's worth.
+
+
+Image Galleries
+---------------
+
+To create an image gallery, all you have to do is add a folder inside ``galleries``,
+and put images there. Nikola will take care of creating thumbnails, index page, etc.
+
+If you click on images on a gallery, you should see a bigger image, thanks to
+the excellent `colorbox <http://www.jacklmoore.com/colorbox>`_
+
+The gallery pages are generated using the ``gallery.tmpl`` template, and you can
+customize it there (you could switch to another lightbox instead of colorbox, change
+its settings, change the layout, etc.).
+
+The ``conf.py`` options affecting gallery pages are these::
+
+    # Galleries are folders in galleries/
+    # Final location of galleries will be output / GALLERY_PATH / gallery_name
+    GALLERY_PATH = "galleries"
+    THUMBNAIL_SIZE = 180
+    MAX_IMAGE_SIZE = 1280
+    USE_FILENAME_AS_TITLE = True
+
+If you add a file in ``galleries/gallery_name/index.txt`` its contents will be
+converted to HTML and inserted above the images in the gallery page.
+
+If you add some image filenames in ``galleries/gallery_name/exclude.meta``, they
+will be excluded in the gallery page.
+
+If ``USE_FILENAME_AS_TITLE`` is True the filename (parsed as a readable string)
+is used as the photo caption. If the filename starts with a number, it will
+be stripped. For example ``03_an_amazing_sunrise.jpg`` will be render as *An amazing sunrise*.
+
+Here is a `demo gallery </galleries/demo>`_ of historic, public domain Nikola
+Tesla pictures taken from `this site <http://kerryr.net/pioneers/gallery/tesla.htm>`_.
+
+Optimizing Your Website
+-----------------------
+
+One of the main goals of Nikola is to make your site fast and light. So here are a few
+tips we have found when setting up Nikola with Apache. If you have more, or
+different ones, or about other webservers, please share!
+
+#. Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and
+   it's probably a good idea to use more than one.
+
+#. Enable compression in Apache::
+
+      AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css
+
+#. If even after you did the previous step the CSS files are not sent compressed::
+
+      AddType text/css .css
+
+In the future we will be adding HTML/CSS/JS minimization and image recompression but
+that's not there yet, so you may want to use 3rd party tools to achieve that.
+
+Restructured Text Extensions
+----------------------------
+
+Nikola includes support for a few directives that are not part of docutils, but which
+we think are handy for website development.
+
+Youtube
+~~~~~~~
+
+To link to a youtube video, you need the id of the video. For example, if the
+URL of the video is http://www.youtube.com/watch?v=8N_tupPBtWQ what you need is
+**8N_tupPBtWQ**
+
+Once you have that, all you need to do is::
+
+    .. youtube:: 8N_tupPBtWQ
+
+code-block
+~~~~~~~~~~
+
+This is a somewhat complicated directive to display code nicely. You can just
+embed code like this::
+
+    .. code-block:: python
+
+        print "Hello World!"
+
+Or you can include the code from a file:
+
+    .. code-block:: python
+       :include: /foo/bar/baz.py
+
+listing
+~~~~~~~
+
+To use this, you have to put your source code files inside ``listings`` or whatever your
+``LISTINGS_FOLDER`` variable is set to. Assuming you have a ``foo.py`` inside that folder::
+
+    .. listing:: foo.py
+
+Will include the source code from ``foo.py`` and also create a ``listings/foo.py.html`` page
+and the listing will have a title linking to it.
+
+Advanced Code Options
+~~~~~~~~~~~~~~~~~~~~~
+
+Both code-block and listing support a number of options, including these:
+
+start-at
+    A string, the diplayed code will start when it finds this
+end-at
+    A string, the diplayed code will end when it finds this
+start-after
+    A string, the diplayed code will start in the line after this
+end-before
+    A string, the diplayed code will end in the line before this
+linenos
+    Display line numbers
+linenos_offset
+    Use the original file's line numbers (warning: broken)
+tab-width
+    Size of the tabs (default 4)
+
+License
+-------
+
+Nikola is released under the `GPL version 3 <http://www.gnu.org/licenses/gpl-3.0.html>`_ which
+is a free software license. Some components shipped along with Nikola, or required by it are
+released under other licenses.
+
+If you are not familiar with free software licensing: In general, you should be able to
+do pretty much anything you want, unless you modify Nikola. If you modify it, and share
+it with someone else, that someone else should get all your modifications under the same
+license you got it.
diff --git a/docs/theming.txt b/docs/theming.txt
new file mode 100644
index 0000000..339ecd4
--- /dev/null
+++ b/docs/theming.txt
@@ -0,0 +1,236 @@
+Theming Nikola
+==============
+
+:Version: 2.1+svn
+:Author: Roberto Alsina <ralsina@netmanagers.com.ar>
+
+.. class:: alert alert-info pull-right
+
+.. contents::
+
+The Structure
+-------------
+
+Themes are located in the ``themes`` folder where Nikola is installed, one folder per theme.
+The folder name is the theme name.
+
+A Nikola theme consists of three folders:
+
+assets
+    This is where you would put your CSS, Javascript and image files. It will be copied
+    into ``output/assets`` when you build the site, and the templates will contain
+    references to them.
+
+    The included themes use `Bootstrap <http://twitter.github.com/bootstrap/>`_
+    and `Colorbox <http://www.jacklmoore.com/colorbox>`_ so they are in assets,
+    along with CSS files for syntax highligting and reStructuredText, and a
+    minified copy of jQuery.
+
+    If you want to base your theme on other frameworks (or on no framework at all)
+    just remember to put there everything you need for deployment.
+
+templates
+    This contains the templates used to generate the pages. While Nikola will use a
+    certain set of template names by default, you can add others for specific parts
+    of your site.
+
+messages
+    Nikola tries to be multilingual. This is where you put the strings for your theme
+    so that it can be translated into other languages.
+
+And these optional files:
+
+parent
+    A text file that, on its first line, contains the name of the **parent theme**. 
+    Any resources missing on this theme, will be looked up in the parent theme 
+    (and then in the grandparent, etc).
+
+    The ``parent`` is so you don't have to create a full theme each time: just create an
+    empty theme, set the parent, and add the bits you want modified.
+
+engine
+    A text file which, on the first line, contains the name of the template engine
+    this theme needs. Currently supported values are "mako" and "jinja".
+    If this file is not given, "mako" is assumed.
+
+bundles
+    A text file containing a list of files to be turned into bundles using WebAssets.
+    For example::
+
+        assets/css/all.css=bootstrap.css,bootstrap-responsive.css,rst.css,code.css,colorbox.css,custom.css
+
+    This creates a file called "assets/css/all.css" in your output that is the
+    combination of all the other file paths, relative to the output file.
+    This makes the page much more efficient because it avoids multiple connections to the server,
+    at the cost of some extra difficult debugging.
+
+    WebAssets supports bundling CSS and JS files.
+
+    Templates should use either the bundle or the individual files based on the ``use_bundles``
+    variable, which in turn is set by the ``USE_BUNDLES`` option.
+
+Creating a New Theme
+--------------------
+
+In your site's folder, create a ``themes`` folder. Choose a theme to start from, and
+create ``themes/yourthemename/parent`` as a file containing the parent theme's name.
+There, you just created a new theme. Of course it looks exactly like the other one,
+so let's customize it.
+
+Templates
+---------
+
+In templates there is a number of files whose name ends in ``.tmpl``. Those are the
+theme's page templates. They are done usig the `Mako <http://makotemplates.org>`_
+template language. If you want to do a theme, you should learn the Mako syntax first.
+
+Mako has a nifty concept of template inheritance. That means that, a
+template can inherit from another and only change small bits of the output. For example,
+``base.tmpl`` defines the whole layout for a page but has only a placeholder for content
+so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``.
+
+These are the templates that come with the included themes:
+
+base.tmpl
+    This template defines the basic page layout for the site. It's mostly plain HTML
+    but defines a few blocks that can be re-defined by inheriting templates:
+
+    * ``extra_head`` is a block that is added before ``</head>``, (ex: for adding extra CSS)
+    * ``belowtitle`` is used by default to display a list of translations but you can put
+      anything there.
+    * ``content`` is where the inheriting templates will place the main content of the page.
+    * ``permalink`` is an absolute path to the page (ex: "/archive/index.html")
+
+    This template always receives the following variables you can use:
+
+    * ``lang`` is the laguage for this page.
+    * ``title`` is the page's title.
+    * ``description`` is the page's description.
+    * ``blog_title`` is the blog's title.
+    * ``blog_author`` is the blog's author.
+    * ``messages`` contains the theme's strings and translations.
+    * ``_link`` is an utility function to create links to other pages in the site.
+      It takes three arguments, kind, name, lang:
+
+      kind is one of:
+
+      * tag_index (name is ignored)
+      * tag (and name is the tag name)
+      * tag_rss (name is the tag name)
+      * archive (and name is the year, or None for the main archive index)
+      * index (name is the number in index-number)
+      * rss (name is ignored)
+      * gallery (name is the gallery name)
+
+      The returned value is always an absolute path, like "/archive/index.html".
+
+    * ``rel_link`` converts absolute paths to relative ones. You can use it with
+      ``_link`` and ``permalink`` to create relative links, which makes the site
+      able to work when moved inside the server. Example: ``rel_link(permalink, url)``
+
+    * Anything you put in your ``GLOBAL_CONTEXT`` option in ``dodo.py``. This
+      usually includes ``sidebar_links``, ``search_form``, and others.
+
+      The included themes use at least these:
+
+      * ``rss_link`` a link to custom RSS feed, although it may be empty)
+      * ``blog_url`` the URL for your site
+      * ``blog_title`` the name of your site
+      * ``content_footer`` things like copyright notices, disclaimers, etc.
+      * ``license`` a larger license badge
+      * ``analytics`` google scripts, or any JS you want to tack at the end of the body
+        of the page.
+      * ``disqus_forum``: a `Disqus <http://disqus.com>`_ ID you can use to enable comments.
+
+    It's probably a bad idea to do a theme that *requires* more than this (please put
+    a ``README`` in it saying what the user should add in its ``dodo.py``), but there is no
+    problem in requiring less.
+
+post.tmpl
+    Template used for blog posts. Can use everything ``base.tmpl`` uses, plus:
+
+    * ``post``: a Post object. This has a number of members:
+
+      * ``post.title(language)``: returns a localized title
+      * ``post.date``
+      * ``post.tags``: A list of tags
+      * ``post.text(language)``: the translated text of the post
+      * ``post.permalink(language, absolute)``: Link to the post in that language.
+        If ``absolute`` is ``True`` the link contains the full URL. This is useful
+        for things like Disqus comment forms.
+      * ``post.next_post`` is None or a Post object that is next newest in the timeline.
+      * ``post.prev_post`` is None or a Post object that is next oldest in the timeline.
+
+story.tmpl
+    Used for pages that are not part of a blog, usually a cleaner, less
+    intrusive layout than ``post.tmpl``, but same parameters.
+
+gallery.tmpl
+    Template used for image galleries. Can use everything ``base.tmpl`` uses, plus:
+
+    * ``text``: A descriptive text for the gallery.
+    * ``images``: A list of (thumbnail, image) paths.
+
+index.tmpl
+    Template used to render the multipost indexes. Can use everything ``base.tmpl`` uses, plus:
+
+    * ``posts``: a list of Post objects, as described above.
+    * ``prevlink``: a link to a previous page
+    * ``nextlink``: a link to the next page
+
+list.tmpl
+    Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus:
+
+    * ``items``: a list of (text, link) elements.
+
+You can add other templates for specific pages, which the user can the use in his ``post_pages``
+option in ``dodo.py``. Also, keep in mind that your theme is yours, there is no reason why
+you would need to maintain the inheritance as it is, or not require whatever data you want.
+
+Messages and Translations
+-------------------------
+
+When you modify templates, you may want to add text in them (for example: "About Me").
+Instead of adding the text directly, which makes it impossible to translate to other
+languages, add it like this::
+
+    ${messages[lang]["About Me"]}
+
+Then, in ``messages/en.py`` add it along the other strings::
+
+    MESSAGES = [
+        u"Posts for year %s",
+        u"Archive",
+        u"Posts about %s:",
+        u"Tags",
+        u"Also available in: ",
+        u"More posts about",
+        u"Posted:",
+        u"Original site",
+        u"Read in english",
+        u"About Me",
+    ]
+
+Then, when I want to use your theme in spanish, all I have to do is add a line in ``messages/es.py``::
+
+    MESSAGES = {
+        u"LANGUAGE": u"Español",
+        u"Posts for year %s": u"Posts del año %s",
+        u"Archive": u"Archivo",
+        u"Posts about %s:": u"Posts sobre %s",
+        u"Tags": u"Tags",
+        u"Also available in: ": u"También disponible en: ",
+        u"More posts about": u"Más posts sobre",
+        u"Posted:": u"Publicado:",
+        u"Original site": u"Sitio original",
+        u"Read in english": u"Leer en español",
+        u"About Me": u"Acerca del autor",
+    }
+
+And voilá, your theme works in spanish. Don't remove strings from these files even if it seems
+your theme is not using them. Some are used internally in Nikola to generate titles and
+similar things.
+
+To create a new translation, just copy one of the existing ones, translate the right side of
+every string to your language, save it and send it to me, I will add it to Nikola!
+