diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/creating-a-theme.txt | 283 | ||||
| -rw-r--r-- | docs/extending.txt | 12 | ||||
| -rw-r--r-- | docs/manual.txt | 85 | ||||
| -rw-r--r-- | docs/theming.txt | 23 |
4 files changed, 376 insertions, 27 deletions
diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt new file mode 100644 index 0000000..0535073 --- /dev/null +++ b/docs/creating-a-theme.txt @@ -0,0 +1,283 @@ +Creating A Theme From Scratch (Almost) +====================================== + +There is some documentation about creating themes for Nikola, but maybe a tutorial is also a useful way +to explain it. So, here it is. I'll explain how to create a theme (almost) from scratch. Alternatively, +you can take an existing theme and modify only parts of it via inheritance, but that's for another +document. + +I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <http://vinicius.soylocoporti.org.br/monospace-wordpress-theme/#.UN4e9lLzu3c>`_. + +.. TEASER_END + +Starting The Theme +------------------ + +First, we create a testing site, and copy the orphan theme from nikola's sources into the right place:: + + $ nikola init monospace-site + A new site with some sample data has been created at monospace-site. + See README.txt in that folder for more information. + + $ cd monospace-site/ + $ mkdir themes + $ cp -RL ~/Desktop/proyectos/nikola/nikola/nikola/data/themes/orphan/ themes/monospace + +The next step is to make the testing site use this new theme, by editing ``conf.py`` and +changing the ``THEME`` option:: + + # Name of the theme to use. Themes are located in themes/theme_name + THEME = 'monospace' + +Now we can already build and test the site:: + + $ nikola build && nikola serve + +.. figure:: http://ralsina.com.ar/galleries/random/monospace-1.png + :height: 400px + + This is the almost completely unstyled "orphan" theme. + +Of course, the page layout is completely broken. To fix that, we need to get into templates. + +Templates: Page Layout +---------------------- + +The general page layout for the theme is done by the ``base.tmpl`` template, which is done using +`Mako <http://www.makotemplates.org/>`_. This is orphan's ``base.tmpl``, it's not very big: + +.. code-block:: mako + + ## -*- coding: utf-8 -*- + <%namespace file="base_helper.tmpl" import="*"/> + <!DOCTYPE html> + <html lang="${lang}"> + <head> + ${html_head()} + <%block name="extra_head"> + </%block> + </head> + <body> + %if add_this_buttons: + <script type="text/javascript">var addthis_config={"ui_language":"${lang}"};</script> + % endif + <h1 id="blog-title"> + <a href="${abs_link('/')}" title="${blog_title}">${blog_title}</a> + </h1> + <%block name="belowtitle"> + %if len(translations) > 1: + <small> + ${(messages[lang][u"Also available in"])}: + ${html_translations()} + </small> + %endif + </%block> + <%block name="content"></%block> + <small>${content_footer}</small> + <!--Sidebar content--> + <ul class="unstyled"> + <li>${license} + ${html_social()} + ${html_sidebar_links()} + <li>${search_form} + </ul> + ${analytics} + <script type="text/javascript">jQuery("a.image-reference").colorbox({rel:"gal",maxWidth:"80%",maxHeight:"80%",scalePhotos:true});</script> + </body> + + +It's basically a HTML document with some placeholders to be replaced with actual content, configuration options, and some helper functions. +For example, the ``html_head`` helper can be used to add CSS or JS files in all document's ``head`` tags. + +Monospace is a two-column-with-footer layout, so let's copy the basics from its HTML and see what happens: + +.. code-block:: mako + + ## -*- coding: utf-8 -*- + <%namespace file="base_helper.tmpl" import="*"/> + <!DOCTYPE html> + <html lang="${lang}"> + <head> + ${html_head()} + <%block name="extra_head"> + </%block> + </head> + <body class="home blog"> + %if add_this_buttons: + <script type="text/javascript">var addthis_config={"ui_language":"${lang}"};</script> + % endif + <div id="wrap" style="width:850px"> + <div id="container" style="width:560px"> + <%block name="content"></%block> + </div> + <div id="sidebar"> + <!--Sidebar content--> + <h1 id="blog-title"> + <a href="${abs_link('/')}" title="${blog_title}">${blog_title}</a> + </h1> + <%block name="belowtitle"> + %if len(translations) > 1: + <small> + ${(messages[lang][u"Also available in"])}: + ${html_translations()} + </small> + %endif + </%block> + <ul class="unstyled"> + <li>${license} + ${html_social()} + ${html_sidebar_links()} + <li>${search_form} + </ul> + </div> + <div id="footer"> + ${content_footer} + </div> + </div> + ${analytics} + <script type="text/javascript">jQuery("a.image-reference").colorbox({rel:"gal",maxWidth:"80%",maxHeight:"80%",scalePhotos:true});</script> + </body> + +.. figure:: http://ralsina.com.ar/galleries/random/monospace-2.png + + Yikes! + +This will get better quickly once we add some CSS + + +Base CSS +-------- + +The orphan theme includes just a little styling, specifically ``rest.css`` so +the restructured text output looks reasonable, and code.css for code snippets. + +It also includes an empty ``assets/css/theme.css`` where you can add your own CSS. +For example, this is taken from the original monospace theme: + +.. code-block:: css + + body { margin:0px; padding:20px 0px; text-align:center; font-family:Monospace; color:#585858; } + .post { margin:0px 0px 30px 0px; padding:0px 0px 30px 0px; border-bottom:1px dotted #C8C8C8; } + .meta { margin:10px; padding:15px; background:#EAEAEA; clear:both; } + #footer { text-align:center; clear:both; margin:30px 0px 0px 0px; padding:30px 0px 0px 0px; border-top:1px dotted #C8C8C8; } + #wrap { margin:0px auto; text-align:left; font-size: 13px; line-height: 1.4; } + #container { float:right; } + #sidebar { overflow:hidden; clear:left; text-align:right; width:250px; height:auto; padding:0px 15px 0px 0px; border-right:1px dotted #C8C8C8; } + #sidebar li { list-style-type:none; } + #sidebar > li { margin:20px 0px; } + #sidebar h1 { border-bottom:1px dotted #C8C8C8; } + #sidebar .description { display:block; width:100%; height:auto; margin:0px 0px 10px 0px; } + +This will (after we rebuild it) make the site looks different of course, and getting closer to our goal: + +.. figure:: http://ralsina.com.ar/galleries/random/monospace-3.png + :height: 400px + + Monospaced allright. + +If you compare it to `the original <http://wp-themes.com/monospace/>`_, however, you will see that the layout of +the posts themselves is different, and that was not described in ``base.tmpl`` at all. But if you look, you'll see that +there is a placeholder called content: ``<%block name="content"></%block>`` + +That's because ``base.tmpl`` defines the *base* layout. The layout of more specific pages, like "the page that shows +a lis of posts" is defined in the other templates. Specifically, this is defined in ``index.tmpl``: + +.. code-block:: mako + + ## -*- coding: utf-8 -*- + <%namespace name="helper" file="index_helper.tmpl"/> + <%inherit file="base.tmpl"/> + <%block name="content"> + % for post in posts: + <div class="post"> + <h1><a href="${post.permalink(lang)}">${post.title(lang)}</a> + <small> + ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} + + </small></h1> + <hr> + ${post.text(lang, index_teasers)} + ${helper.html_disqus_link(post)} + </div> + % endfor + ${helper.html_pager()} + ${helper.html_disqus_script()} + </%block> + +So, let's tweak that to be closer to the original. We put the post's metadata in a +box, add links for the posts tags, move the date there, etc. + +.. code-block:: mako + + ## -*- coding: utf-8 -*- + <%namespace name="helper" file="index_helper.tmpl"/> + <%inherit file="base.tmpl"/> + <%block name="content"> + % for post in posts: + <div class="postbox"> + <h1><a href="${post.permalink(lang)}">${post.title(lang)}</a></h1> + <div class="meta" style="background-color: rgb(234, 234, 234); "> + <span class="authordate"> + ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} + </span> + <br> + <span class="tags">Tags: + %if post.tags: + %for tag in post.tags: + <a class="tag" href="${_link('tag', tag, lang)}"><span class="badge badge-info">${tag}</span></a> + %endfor + %endif + </span> + </div> + ${post.text(lang, index_teasers)} + ${helper.html_disqus_link(post)} + </div> + % endfor + ${helper.html_pager()} + +.. figure:: http://ralsina.com.ar/galleries/random/monospace-4.png + :height: 400px + + Close enough! + +Then if we click on the post title, we will see some broken details in the metadata that can be fixed in ``post.tmpl``, and so on. + +.. code-block:: mako + + ## -*- coding: utf-8 -*- + <%namespace name="helper" file="post_helper.tmpl"/> + <%inherit file="base.tmpl"/> + <%block name="content"> + <div class="post"> + ${helper.html_title()} + <div class="meta" style="background-color: rgb(234, 234, 234); "> + <span class="authordate"> + ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} [<a href="${post.pagenames[lang]+'.txt'}">${messages[lang]["Source"]}</a>] + </span> + <br> + %if post.tags: + <span class="tags">${messages[lang]["Tags"]}: + %for tag in post.tags: + <a class="tag" href="${_link('tag', tag, lang)}"><span class="badge badge-info">${tag}</span></a> + %endfor + </span> + <br> + %endif + <span class="authordate"> + ${helper.html_translations(post)} + </span> + </div> + ${post.text(lang)} + ${helper.html_pager(post)} + ${helper.html_disqus(post)} + </div> + </%block> + +.. figure:: http://ralsina.com.ar/galleries/random/monospace-5.png + :height: 400px + + Details, details. + +The demo site exercises most of the features in Nikola, so if you make it look good, your site probably will look good too. +This monospace theme is included with nikola, if you want to use it or play with it. + diff --git a/docs/extending.txt b/docs/extending.txt index 4bbc2ea..6410e69 100644 --- a/docs/extending.txt +++ b/docs/extending.txt @@ -52,7 +52,7 @@ Each and every one of those is a plugin. Let's look at a typical example: First, the ``command_serve.plugin`` file: -.. code_block:: init +.. code-block:: init [Core] Name = serve @@ -68,7 +68,7 @@ For your own plugin, just change the values in a sensible way. The ``Module`` will be used to find the matching python module, in this case ``command_serve.py``, from which this is the interesting bit: -.. code_block:: python +.. code-block:: python from nikola.plugin_categories import Command @@ -144,7 +144,7 @@ Nikola supports Mako and Jinja2. If you prefer some other templating system, then you will have to write a TemplateSystem plugin. Here's how they work. First, you have to create a .plugin file. Here's the one for the Mako plugin: -.. code_block:: ini +.. code-block:: ini [Core] Name = mako @@ -162,7 +162,7 @@ in the obvious ways. The "Module" option is the name of the module, which has to look something like this, a stub for a hypothetical system called "Templater": -.. code_block:: python +.. code-block:: python from nikola.plugin_categories import TemplateSystem @@ -240,7 +240,7 @@ document, so I'll just leave you with an example, the ``copy_assets`` task. First the ``task_copy_assets.plugin`` file, which you should copy and edit in the logical ways: -.. code_block:: ini +.. code-block:: ini [Core] Name = copy_assets @@ -254,7 +254,7 @@ in the logical ways: And the ``task_copy_assets.py`` file, in its entirety: -.. code_block:: python +.. code-block:: python import os diff --git a/docs/manual.txt b/docs/manual.txt index 202afc1..ac15d8b 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -1,7 +1,7 @@ The Nikola Handbook =================== -:Version: 5 +:Version: 5.1 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -169,6 +169,8 @@ If you want to create a blog or a site, Nikola provides: `Markdown <http://daringfireball.net/projects/markdown/>`_) * Easy-to-create image galleries * Support for displaying source code +* Image slideshows +* Client-side cloud tags Also: @@ -194,13 +196,13 @@ Longer version: #. ``pip install -r requirements.txt`` or... #. Install your distribution's packages for all the things mentioned below, if they exist, or... - #. Get all of these manually: + #. Get all of these manually (but why?, use requirements.txt): #. 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 `PIL <http://www.pythonware.com/products/pil/>`_ (or Pillow) #. Get `Pygments <http://pygments.org/>`_ #. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ #. Get `lxml <http://lxml.de/>`_ @@ -212,10 +214,7 @@ Longer version: After that, run ``nikola init sitename`` and that will create a folder called ``sitename`` containing a functional demo site. -.. note:: Are you using Ubuntu? - - Then you can try using `my PPA <https://launchpad.net/~ralsina/+archive/nikola>`_ - and installing python-nikola +Nikola is packaged for some Linux distributions, you may get that instead. Getting Started --------------- @@ -786,7 +785,7 @@ embed code like this:: print "Hello World!" -Or you can include the code from a file: +Or you can include the code from a file:: .. code-block:: python :include: /foo/bar/baz.py @@ -797,10 +796,10 @@ 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 + .. listing:: foo.py python -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. +Will include the source code from ``foo.py``, highlight its syntax in python mode, +and also create a ``listings/foo.py.html`` page and the listing will have a title linking to it. Advanced Code Options ~~~~~~~~~~~~~~~~~~~~~ @@ -822,10 +821,72 @@ linenos_offset tab-width Size of the tabs (default 4) +Slideshows +~~~~~~~~~~ + +To create an image slideshow, you can use the ``slides`` directive. For example:: + + .. slides:: + :preload: + :play: 350 + + /galleries/demo/tesla_conducts_lg.jpg + /galleries/demo/tesla_lightning2_lg.jpg + /galleries/demo/tesla4_lg.jpg + /galleries/demo/tesla_lightning1_lg.jpg + /galleries/demo/tesla_tower1_lg.jpg + +This is based on `slidejs <http://slidesjs.com/>`_ and it supports +`the options described there <http://slidesjs.com/#options>`_ with one minor tweak to make them +fit in docutils convention: If the option takes a boolean value, you just have to add it or not. For example, +to enable preloading, just use the ``:preload:`` option. + +If the option takes any other kind of argument, just use it after the option, like ``play`` in the +above example. + +Importing Your Wordpress Site Into Nikola +----------------------------------------- + +If you like Nikola, and want to start using it, but you have a Wordpress blog, Nikola +supports importing it. Here's the steps to do it: + +1) Get a XML dump of your site [#]_ +2) nikola import_wordpress mysite.wordpress.2012-12-20.xml + +After some time, this will crate a ``new_site`` folder with all your data. It currently supports +the following: + +* All your posts and pages +* Keeps "draft" status +* Your tags and categories +* Imports your attachments and fixes links to point to the right places +* Will try to add redirects that send the old post URLs to the new ones +* Will give you a url_map so you know where each old post was + + This is also useful for Disqus thread migration! + +* Will try to convert the content of your posts. This is *not* error free, because + wordpress uses some unholy mix of HTML and strange things. Currently we are treating it + as markdown, which does a reasonabe job of it. + + You will find your old posts in ``new_site/posts/post-title.wp`` in case you need to fix + any of them. + +This feature is a work in progress, and the only way to improve it is to have it used for +as many sites as possible and make it work better each time, so I am happy to get requests +about it. + +.. [#] The dump needs to be in 1.2 format. You can check by reading it, it should say + ``xmlns:excerpt="http://wordpress.org/export/1.2/excerpt/"`` near the top of the + file. If it says ``1.1`` instead of ``1.2`` you will have to update your + wordpress before dumping. + + Other versions may or may not work. + License ------- -Nikola is released under the `GPL version 3 <http://www.gnu.org/licenses/gpl-3.0.html>`_ which +Nikola is released under a `MIT license <https://github.com/ralsina/nikola/blob/master/LICENSE.txt>`_ which is a free software license. Some components shipped along with Nikola, or required by it are released under other licenses. diff --git a/docs/theming.txt b/docs/theming.txt index 93c7824..33884e9 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -8,6 +8,9 @@ Theming Nikola .. contents:: +This document is a reference about themes. If you want a tutorial, please read +`Creating a Theme <creating-a-theme.html>`_ + The Structure ------------- @@ -69,20 +72,15 @@ bundles 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. +or `Jinja2 <jinja.pocoo.org>`_ template languages. If you want to do a theme, you +should learn one first. What engine is used by the theme is declared in the ``engine`` file. + +The rest of this document explains Mako templates, but Jinja2 is fairly similar. 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, @@ -183,6 +181,13 @@ list.tmpl * ``items``: a list of (text, link) elements. + +list_post.tmpl + Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus: + + * ``posts``: a list of Post objects. + + 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. |