diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/creating-a-site.txt | 42 | ||||
| -rw-r--r-- | docs/creating-a-theme.txt | 257 | ||||
| -rw-r--r-- | docs/extending.txt | 269 | ||||
| -rw-r--r-- | docs/internals.txt | 37 | ||||
| -rw-r--r-- | docs/man/nikola.1 | 148 | ||||
| -rw-r--r-- | docs/manual.txt | 719 | ||||
| -rw-r--r-- | docs/social_buttons.txt | 202 | ||||
| -rw-r--r-- | docs/sphinx/Makefile | 177 | ||||
| -rw-r--r-- | docs/sphinx/conf.py | 263 | ||||
| l--------- | docs/sphinx/creating-a-site.txt | 1 | ||||
| l--------- | docs/sphinx/creating-a-theme.txt | 1 | ||||
| l--------- | docs/sphinx/extending.txt | 1 | ||||
| -rw-r--r-- | docs/sphinx/index.txt | 27 | ||||
| l--------- | docs/sphinx/internals.txt | 1 | ||||
| -rw-r--r-- | docs/sphinx/make.bat | 242 | ||||
| l--------- | docs/sphinx/manual.txt | 1 | ||||
| l--------- | docs/sphinx/social_buttons.txt | 1 | ||||
| l--------- | docs/sphinx/theming.txt | 1 | ||||
| l--------- | docs/sphinx/upgrading-to-v6.txt | 1 | ||||
| -rw-r--r-- | docs/theming.txt | 204 | ||||
| -rw-r--r-- | docs/upgrading-to-v6.txt | 81 |
21 files changed, 2170 insertions, 506 deletions
diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt index 41985c9..a200d54 100644 --- a/docs/creating-a-site.txt +++ b/docs/creating-a-site.txt @@ -3,16 +3,17 @@ .. tags: nikola, python .. link: .. description: +.. title: Creating a Site (Not a Blog) with Nikola Creating a Site (Not a Blog) with Nikola ======================================== -One of the most frequent questions I get about Nikola is "but how do +One of the most frequent questions I get about Nikola is "but how do I create a site that's not a blog?". And of course, that's because the documentation is heavily blog-oriented. This document will change that ;-) Since it started, Nikola has had the capabilities to create generic sites. For example, -Nikola's `own site <http://nikola.ralsina.com.ar>`_ is a fairly generic one. Let's go +Nikola's `own site <http://getnikola.com>`_ is a fairly generic one. Let's go step by step on how you can do something like that. As usual when starting a nikola site, you start with ``nikola init`` which creates a @@ -45,9 +46,13 @@ configuration file: # Some things in the middle you don't really need to change... # - post_pages = ( - ("pages/*.txt", "", "story.tmpl", False), - ) + POSTS = [] + PAGES = [("pages/*.txt", "", "story.tmpl")] + + # And to avoid a conflict because blogs try to generate /index.html + INDEX_PATH = "blog" + + And now we are ready to create our first page:: @@ -96,12 +101,12 @@ not-blogs, same for tags and link. Description is useful for SEO purposes if you care for that. And below, the content. By default you are expected to use -`reStructured text <http://nikola.ralsina.com.ar/quickstart.html>`_ but +`reStructuredText <http://getnikola.com/quickstart.html>`_ but Nikola supports a ton of formats, including Markdown, plain HTML, BBCode, Wiki, and Textile. So, let's give the page a nicer title, and some fake content. Since the default -Nikola theme (called "site") is based on `bootstrap <http://twitter.github.com/bootstrap/>`_ +Nikola theme (called "bootstrap") is based on `bootstrap 2 <http://getbootstrap.com/2.3.2/>`_ you can use anything you like from it: .. code-block:: rest @@ -144,36 +149,23 @@ you can use anything you like from it: .. admonition:: TIP: Nice URLs If you like your URLs without the ".html" then you want to create folders and - put the pages in ``index.html`` inside them. Example:: - - nikola new_post -p pages/foo/index.txt - - which will create a page you could access as "http://yoursite.com/foo" + put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option. -And that's it. You will want to change the SIDEBAR_LINKS option to create a reasonable +And that's it. You will want to change the NAVIGATION_LINKS option to create a reasonable "menu" for your site, you will want to hack the theme (check ``nikola help bootswatch_theme`` for a quick & dirty solution), and you may want to add a blog later on, for company news or whatever. .. admonition:: TIP: So, how do I add a blog now? - First, change the ``post_pages`` option like this: - - .. code-block:: python - - post_pages = ( - ("pages/*.txt", "", "story.tmpl", False), - ("posts/*.txt", "blog", "post.tmpl", True), - ) - - And to avoid a conflict (because blogs try to generate ``/index.html``: + First, change the ``POSTS`` option like this: .. code-block:: python - INDEX_PATH = "blog" + POSTS = [("posts/*.txt", "blog", "post.tmpl", True)] Create a post with ``nikola new_post`` and that's it, you now have a blog - in http://yoursite.com/blog (you may want to add links to it in SIDEBAR_LINKS of course). + in http://yoursite.com/blog (you may want to add links to it in NAVIGATION_LINKS of course). You can see the finished site in http://notablog.ralsina.com.ar and its full configuration in http://ralsina.com.ar/listings/notablog/conf.py.html diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt index 11428bd..1e67410 100644 --- a/docs/creating-a-theme.txt +++ b/docs/creating-a-theme.txt @@ -1,27 +1,40 @@ +.. title: Creating a Theme +.. slug: creating-a-theme +.. date: 2012/03/13 12:00 +.. tags: +.. link: +.. description: + 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. +to explain it. So, here it is. I'll explain how to create a theme (almost) from scratch. All themes +in Nikola must inherit from the ``base`` theme. In this case, we will inherit from ``bootstrap`` +so we get good support for slides and galleries. -I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <http://vinicius.soylocoporti.org.br/monospace-wordpress-theme/#.UN4e9lLzu3c>`_. +I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <http://wordpress.org/themes/monospace>`_. .. TEASER_END Starting The Theme ------------------ -First, we create a testing site, and copy the orphan theme from nikola's sources into the right place:: +First we will create a testing site:: $ nikola init --demo 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/ + +Our theme will inherit from the ``bootstrap`` theme, which is full-featured but boring. + +:: + $ mkdir themes - $ cp -RL ~/Desktop/proyectos/nikola/nikola/nikola/data/themes/orphan/ themes/monospace + $ mkdir themes/monospace + $ echo bootstrap > themes/monospace/parent The next step is to make the testing site use this new theme, by editing ``conf.py`` and changing the ``THEME`` option:: @@ -33,56 +46,99 @@ Now we can already build and test the site:: $ nikola build && nikola serve -.. figure:: http://ralsina.com.ar/galleries/random/monospace-1.png +.. figure:: http://ralsina.com.ar/galleries/monospace-tut/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. + This is the default "bootstrap" theme. + +Of course, the page layout is completely different from what we want. 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: +`Mako <http://www.makotemplates.org/>`_. This is bootstrap's ``base.tmpl``, it's not very big: .. code-block:: mako ## -*- coding: utf-8 -*- - <%namespace file="base_helper.tmpl" import="*"/> + <%namespace name="base" file="base_helper.tmpl" import="*" /> + <%namespace name="bootstrap" file="bootstrap_helper.tmpl" import="*" /> + ${set_locale(lang)} <!DOCTYPE html> - <html lang="${lang}"> + <html% if comment_system == 'facebook': xmlns:fb="http://ogp.me/ns/fb#" %endif lang="${lang}"> <head> - ${html_head()} + <meta name="viewport" content="width=device-width, initial-scale=1.0"> + ${bootstrap.html_head()} <%block name="extra_head"> </%block> + ${extra_head_data} </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> + <!-- Menubar --> + <div class="navbar navbar-fixed-top" id="navbar"> + <div class="navbar-inner"> + <div class="container"> + + <!-- .btn-navbar is used as the toggle for collapsed navbar content --> + <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </a> + + <a class="brand" href="${abs_link('/')}"> + ${blog_title} + </a> + <!-- Everything you want hidden at 940px or less, place within here --> + <div class="nav-collapse collapse"> + <ul class="nav"> + ${bootstrap.html_navigation_links()} + </ul> + %if search_form: + ${search_form} + %endif + <ul class="nav pull-right"> + <%block name="belowtitle"> + %if len(translations) > 1: + <li>${base.html_translations()}</li> + %endif + </%block> + % if not hide_sourcelink: + <li><%block name="sourcelink"></%block></li> + %endif + </ul> + </div> + </div> + </div> + </div> + <!-- End of Menubar --> + <div class="container-fluid" id="container-fluid"> + <!--Body content--> + <div class="row-fluid"> + <div class="span2"></div> + <div class="span8"> + <%block name="content"></%block> + </div> + </div> + <!--End of body content--> + </div> + <div class="footerbox"> + ${content_footer} + </div> + ${bootstrap.late_load_js()} + ${base.html_social()} + <script type="text/javascript">jQuery("a.image-reference").colorbox({rel:"gal",maxWidth:"100%",maxHeight:"100%",scalePhotos:true}); + $(window).on('hashchange', function(){ + if (location.hash && $(location.hash)[0]) { + $('body').animate({scrollTop: $(location.hash).offset().top - $('#navbar').outerHeight(true)*1.2 }, 1); + } + }); + $(document).ready(function(){$(window).trigger('hashchange')}); + </script> + <%block name="extra_js"></%block> + ${body_end} </body> @@ -94,18 +150,18 @@ Monospace is a two-column-with-footer layout, so let's copy the basics from its .. code-block:: mako ## -*- coding: utf-8 -*- - <%namespace file="base_helper.tmpl" import="*"/> + <%namespace name="base" file="base_helper.tmpl" import="*"/> + <%namespace name="bootstrap" file="bootstrap_helper.tmpl" import="*" /> + ${set_locale(lang)} <!DOCTYPE html> <html lang="${lang}"> <head> - ${html_head()} + ${bootstrap.html_head()} <%block name="extra_head"> </%block> + ${extra_head_data} </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> @@ -118,30 +174,32 @@ Monospace is a two-column-with-footer layout, so let's copy the basics from its <%block name="belowtitle"> %if len(translations) > 1: <small> - ${(messages[lang][u"Also available in"])}: - ${html_translations()} + ${(messages("Also available in"))}: + ${base.html_translations()} </small> %endif </%block> <ul class="unstyled"> <li>${license} - ${html_social()} - ${html_sidebar_links()} + ${base.html_social()} + ${bootstrap.html_navigation_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> + </div> + ${bootstrap.late_load_js()} + <script type="text/javascript">jQuery("a.image-reference").colorbox({rel:"gal",maxWidth:"100%",maxHeight:"100%",scalePhotos:true});</script> + <%block name="extra_js"></%block> + ${body_end} </body> -.. figure:: http://ralsina.com.ar/galleries/random/monospace-2.png +.. figure:: http://ralsina.com.ar/galleries/monospace-tut/monospace-2.png Yikes! - + This will get better quickly once we add some CSS @@ -149,10 +207,11 @@ 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. +the reStructuredText 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: +For example, this is taken from the original monospace theme, except for the last +few selectors: .. code-block:: css @@ -167,44 +226,61 @@ For example, this is taken from the original monospace theme: #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; } - + h1, h2, h3, h4, h5, h6, h7 { margin:0px; text-transform:uppercase; } + h4, h5, h6 { font-size:14px; } + #blog-title { margin-top: 0; line-height:48px;} + .literal-block {padding: .5em;} + div.sidebar, div.admonition, div.attention, div.caution, div.danger, div.error, div.hint, div.important, div.note, div.tip, div.warning { + /* Issue 277 */ + border: 1px solid #aaa; + border-radius: 5px; + width: 100%; + } + ul.breadcrumb > li:before { + content: " / "; + } + 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 +.. figure:: http://ralsina.com.ar/galleries/monospace-tut/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 list of posts" is defined in the other templates. Specifically, this is defined in ``index.tmpl``: +a list of posts" is defined in the other templates. Specifically, this is defined in ``index.tmpl``. +It turns out ``bootstrap`` doesn' have one of those! That's because it inherits that template from ``base``: .. code-block:: mako ## -*- coding: utf-8 -*- <%namespace name="helper" file="index_helper.tmpl"/> + <%namespace name="comments" file="comments_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> + <div class="postbox"> + <h1><a href="${post.permalink()}">${post.title()}</a> <small> - ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} - + ${messages("Posted")}: <time class="published" datetime="${post.date.isoformat()}">${post.formatted_date(date_format)}</time> </small></h1> <hr> - ${post.text(lang, index_teasers)} - ${helper.html_disqus_link(post)} + ${post.text(teaser_only=index_teasers)} + % if not post.meta('nocomments'): + ${comments.comment_link(post.permalink(), post.base_path)} + % endif </div> % endfor ${helper.html_pager()} - ${helper.html_disqus_script()} + ${comments.comment_link_script()} + ${helper.mathjax_script(posts)} </%block> -So, let's tweak that to be closer to the original. We put the post's metadata in a +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 @@ -216,53 +292,65 @@ box, add links for the posts tags, move the date there, etc. <%block name="content"> % for post in posts: <div class="postbox"> - <h1><a href="${post.permalink(lang)}">${post.title(lang)}</a></h1> + <h1><a href="${post.permalink()}">${post.title()}</a></h1> <div class="meta" style="background-color: rgb(234, 234, 234); "> <span class="authordate"> - ${messages[lang]["Posted"]}: ${post.date.strftime(date_format)} + ${messages("Posted")}: ${post.formatted_date(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> + <a class="tag" href="${_link('tag', tag)}"><span>${tag}</span></a> %endfor %endif </span> </div> - ${post.text(lang, index_teasers)} - ${disqus.html_disqus_link(post.permalink()+"#disqus_thread", post.base_path)} + ${post.text(teaser_only=index_teasers)} + % if not post.meta('nocomments'): + ${disqus.html_disqus_link(post.permalink()+"#disqus_thread", post.base_path)} + % endif </div> % endfor ${helper.html_pager()} ${disqus.html_disqus_script()} </%block> -.. figure:: http://ralsina.com.ar/galleries/random/monospace-4.png + +.. figure:: http://ralsina.com.ar/galleries/monospace-tut/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"/> <%namespace name="disqus" file="disqus_helper.tmpl"/> <%inherit file="base.tmpl"/> + <%block name="extra_head"> + ${helper.twitter_card_information(post)} + % if post.meta('keywords'): + <meta name="keywords" content="${post.meta('keywords')|h}"/> + % endif + </%block> <%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>] + ${messages("Posted")}: ${post.formatted_date(date_format)} + % if not post.meta('password'): + [<a href="${post.source_link()}" id="sourcelink">${messages("Source")}</a>] + % endif </span> <br> %if post.tags: - <span class="tags">${messages[lang]["Tags"]}: + <span class="tags">${messages("Tags")}: %for tag in post.tags: - <a class="tag" href="${_link('tag', tag, lang)}"><span class="badge badge-info">${tag}</span></a> + <a class="tag" href="${_link('tag', tag)}"><span>${tag}</span></a> %endfor </span> <br> @@ -271,17 +359,20 @@ Then if we click on the post title, we will see some broken details in the metad ${helper.html_translations(post)} </span> </div> - ${post.text(lang)} + ${post.text()} ${helper.html_pager(post)} - ${disqus.html_disqus(post.permalink(absolute=True), post.title(lang), post.base_path)} + % if not post.meta('nocomments'): + ${disqus.html_disqus(post.permalink(absolute=True), post.title(), post.base_path)} + % endif </div> </%block> -.. figure:: http://ralsina.com.ar/galleries/random/monospace-5.png + +.. figure:: http://ralsina.com.ar/galleries/monospace-tut/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 750ec98..f5c7aae 100644 --- a/docs/extending.txt +++ b/docs/extending.txt @@ -1,7 +1,14 @@ +.. title: Extending Nikola +.. slug: extending +.. date: 2012/03/30 23:00 +.. tags: +.. link: +.. description: + Extending Nikola ================ -:Version: 5 +:Version: 6.2.1 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -9,11 +16,6 @@ Extending Nikola .. contents:: -.. note:: This is a draft - - I am not sure of the best way to do some things, including how - to document this. Suggestions are welcome. - Nikola is extensible. Almost all its functionality is based on plugins, and you can add your own or replace the provided ones. @@ -32,20 +34,42 @@ Command Plugins When you run ``nikola --help`` you will see something like this:: - $ nikola --help - Usage: nikola command [options] + $ nikola help + Nikola is a tool to create static websites and blogs. For full documentation and more + information, please visit http://getnikola.com - Available commands: - nikola bootswatch_theme: Given a swatch name and a parent theme, creates a custom theme. - nikola build: Build the site. - nikola import_wordpress: Import a wordpress site from a XML dump. - nikola init: Create a new site. - nikola install_theme: Install a theme into the current site. - nikola new_post: Create a new post. - nikola serve: Start test server. - - For detailed help for a command, use nikola command --help + Available commands: + nikola auto automatically detect site changes, rebuild + and optionally refresh a browser + nikola bootswatch_theme given a swatch name from bootswatch.com and a + parent theme, creates a custom theme + nikola build run tasks + nikola check check links and files in the generated site + nikola clean clean action / remove targets + nikola console start an interactive python console with access to + your site and configuration + nikola deploy deploy the site + nikola dumpdb dump dependency DB + nikola forget clear successful run status from internal DB + nikola help show help + nikola ignore ignore task (skip) on subsequent runs + nikola import_blogger import a blogger dump + nikola import_feed import a RSS/Atom dump + nikola import_wordpress import a WordPress dump + nikola init create a Nikola site in the specified folder + nikola install_theme install theme into current site + nikola list list tasks from dodo file + nikola mincss apply mincss to the generated site + nikola new_post create a new blog post or site page + nikola run run tasks + nikola serve start the test webserver + nikola strace use strace to list file_deps and targets + nikola version print the Nikola version number + + nikola help show help / reference + nikola help <command> show command usage + nikola help <task-name> show task usage That will give you a list of all available commands in your version of Nikola. Each and every one of those is a plugin. Let's look at a typical example: @@ -56,17 +80,22 @@ First, the ``command_serve.plugin`` file: [Core] Name = serve - Module = command_serve + Module = serve [Documentation] Author = Roberto Alsina Version = 0.1 - Website = http://nikola.ralsina.com.ar + Website = http://getnikola.com Description = Start test server. +.. note:: If you want to publish your plugin on the Plugin Index, `read + the docs for the Index + <https://github.com/getnikola/plugins/blob/master/README.md>`__ + (and the .plugin file examples and explanations). + 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: +``serve.py``, from which this is the interesting bit: .. code-block:: python @@ -78,57 +107,52 @@ For your own plugin, just change the values in a sensible way. The class CommandBuild(Command): """Start test server.""" - # This has to match the Name option in the .plugin file - name = "serve" - - # This is the function that does stuff - - def run(self, *args): + doc_usage = "[options]" + doc_purpose = "start the test webserver" + + cmd_options = ( + { + 'name': 'port', + 'short': 'p', + 'long': 'port', + 'default': 8000, + 'type': int, + 'help': 'Port nummber (default: 8000)', + }, + { + 'name': 'address', + 'short': 'a', + 'long': '--address', + 'type': str, + 'default': '127.0.0.1', + 'help': 'Address to bind (default: 127.0.0.1)', + }, + ) + + def _execute(self, options, args): """Start test server.""" - - # use OptionParser if you want your command to have options - - parser = OptionParser(usage="nikola %s [options]" % self.name) - parser.add_option("-p", "--port", dest="port", - help="Port numer (default: 8000)", default=8000, - type="int") - parser.add_option("-a", "--address", dest="address", - help="Address to bind (default: 127.0.0.1)", - default='127.0.0.1') - (options, args) = parser.parse_args(list(args)) - - # You can use self.site.config to access your - # configuration options. self.site is an instance - # of the Nikola class and contains all your site's - # data. - out_dir = self.site.config['OUTPUT_FOLDER'] - - # Then do something interesting. In this case, - # it starts a webserver - if not os.path.isdir(out_dir): - print "Error: Missing '%s' folder?" % out_dir + print("Error: Missing '{0}' folder?".format(out_dir)) else: os.chdir(out_dir) - httpd = HTTPServer((options.address, options.port), - OurHTTPRequestHandler) + httpd = HTTPServer((options['address'], options['port']), + OurHTTPRequestHandler) sa = httpd.socket.getsockname() - print "Serving HTTP on", sa[0], "port", sa[1], "..." + print("Serving HTTP on", sa[0], "port", sa[1], "...") httpd.serve_forever() As mentioned above, a plugin can have options, which the user can see by doing -``nikola command --help`` and can later use as ``nikola command --option``:: +``nikola help command`` and can later use, for example:: - $ nikola serve --help - Usage: nikola serve [options] + $ nikola help serve + Purpose: start the test webserver + Usage: nikola serve [options] Options: - -h, --help show this help message and exit - -p PORT, --port=PORT Port numer (default: 8000) - -a ADDRESS, --address=ADDRESS - Address to bind (default: 127.0.0.1) + -p ARG, --port=ARG Port nummber (default: 8000) + -a ARG, ----address=ARG Address to bind (default: 127.0.0.1) $ nikola serve -p 9000 Serving HTTP on 127.0.0.1 port 9000 ... @@ -148,14 +172,19 @@ First, you have to create a .plugin file. Here's the one for the Mako plugin: [Core] Name = mako - Module = template_mako + Module = mako [Documentation] Author = Roberto Alsina Version = 0.1 - Website = http://nikola.ralsina.com.ar + Website = http://getnikola.com Description = Support for Mako templates. +.. note:: If you want to publish your plugin on the Plugin Index, `read + the docs for the Index + <https://github.com/getnikola/plugins/blob/master/README.md>`__ + (and the .plugin file examples and explanations). + You will have to replace "mako" with your template system's name, and other data in the obvious ways. @@ -187,13 +216,13 @@ a stub for a hypothetical system called "Templater": # template loading tool that can use this. def set_directories(self, directories): - """Createa template lookup.""" + """Create a template lookup.""" pass # The method that does the actual rendering. # template_name is the name of the template file, # output_name is the file for the output, context - # is a dictionary containing the data the template + # is a dictionary containing the data the template # uses for rendering. def render_template(self, template_name, output_name, @@ -208,17 +237,27 @@ Task Plugins If you want to do something that depends on the data in your site, you probably want to do a Task plugin, which will make it be part of the ``nikola build`` command. There are the currently available tasks, all -provided by plugins:: +provided by plugins: - $ nikola list +.. sidebar:: Other Tasks + + There are also ``LateTask`` plugins, which are executed later, + and ``TaskMultiplier`` plugins that take a task and create + more tasks out of it. +:: + + $ nikola list + Scanning posts....done! build_bundles + build_less copy_assets copy_files - deploy + post_render redirect render_archive render_galleries + render_galleries_clean render_indexes render_listings render_pages @@ -249,9 +288,15 @@ in the logical ways: [Documentation] Author = Roberto Alsina Version = 0.1 - Website = http://nikola.ralsina.com.ar + Website = http://getnikola.com Description = Copy theme assets into output. + +.. note:: If you want to publish your plugin on the Plugin Index, `read + the docs for the Index + <https://github.com/getnikola/plugins/blob/master/README.md>`_ + (and the .plugin file examples and explanations). + And the ``task_copy_assets.py`` file, in its entirety: .. code-block:: python @@ -299,3 +344,93 @@ And the ``task_copy_assets.py`` file, in its entirety: task['basename'] = self.name # If your task generates files, please do this. yield utils.apply_filters(task, kw['filters']) + +PageCompiler Plugins +-------------------- + +These plugins implement markup languages, they take sources for posts or pages and +create HTML or other output files. A good example is the ``misaka`` plugin. + +They must provide: + +``compile_html`` + Function that builds a file. + +``create_post`` + Function that creates an empty file with some metadata in it. + +If the compiler produces something other than HTML files, it should also implement ``extension`` which +returns the preferred extension for the output file. + +RestExtension Plugins +--------------------- + +Implement directives for reStructuredText, see ``media.py`` for a simple example. + +SignalHandler Plugins +--------------------- + +These plugins extend the ``SignalHandler`` class and connect to one or more +signals via `blinker <http://pythonhosted.org/blinker/>`_ + +The easiest way to do this is to reimplement ``set_site()`` and just connect to +whatever signals you want there. + +Currently Nikola emits the following signals: + +``sighandlers_loaded`` + Right after SignalHandler plugin activation. +``initialized`` + Right after plugin activation +``configured`` + When all the configuration file is processed. Note that plugins are activated before this is emitted. +``new_post`` + When a new post is created, using the ``nikola new_post`` command. The signal + data contains the path of the file, and the metadata file (if there is one). +``deployed`` + When the ``nikola deploy`` command is run, and there is at least one new + entry/post since ``last_deploy``. The signal data is of the form :: + + { + 'last_deploy: # datetime object for the last deployed time, + 'new_deploy': # datetime object for the current deployed time, + 'clean': # whether there was a record of a last deployment, + 'deployed': # all files deployed after the last deploy, + 'undeployed': # all files not deployed since they are either future posts/drafts + } + + +Plugin Index +============ + +There is a `plugin index <http://plugins.getnikola.com/>`__, which stores all +of the plugins for Nikola people wanted to share with the world. + +You may want to read the `README for the Index +<https://github.com/getnikola/plugins/blob/master/README.md>`_ if you want to +publish your package there. + +Path/Link Resolution Mechanism +============================== + +Any plugin can register a function using ``Nikola.register_path_handler`` to +allow resolution of paths and links. These are useful for templates, which +can access them via _link. + +For example, you can always get a link to the path for the feed of the "foo" tag +by using ``_link('tag_rss', 'foo')`` or the ``link://tag_rss/foo`` URL. + +Here's the relevant code from the tag plugin. + +.. code-block:: python + + # In set_site + site.register_path_handler('tag_rss', self.tag_rss_path) + + # And these always take name and lang as arguments and returl a list of + # path elements. + def tag_rss_path(self, name, lang): + return [_f for _f in [self.site.config['TRANSLATIONS'][lang], + self.site.config['TAG_PATH'], self.slugify_name(name) + ".xml"] if + _f] + diff --git a/docs/internals.txt b/docs/internals.txt index 7a38f27..14de433 100644 --- a/docs/internals.txt +++ b/docs/internals.txt @@ -1,3 +1,10 @@ +.. title: Nikola Internals +.. slug: internals +.. date: 2012/03/30 23:00 +.. tags: +.. link: +.. description: + Nikola Internals ================ @@ -16,14 +23,15 @@ Nikola is a Pile of Plugins an existing one. There are several kinds of plugins, all implementing interfaces defined in - ``nikola/plugin_categories.py``. + ``nikola/plugin_categories.py`` and documented in + `Extending Nikola <http://getnikola.com/extending.html>`_ If your plugin has a dependency, please make sure it doesn't make Nikola throw an exception when the dependency is missing. Try to fail gracefully with an informative message. Commands are plugins - When you use ``nikola foo`` you are using the plugin ``command_foo``. Those are + When you use ``nikola foo`` you are using the plugin ``command/foo``. Those are used to extend Nikola's command line. Their interface is defined in the ``Command`` class. They take options and arguments and do whatever you want, so go wild. @@ -36,7 +44,7 @@ The Build Command Nikola's goal is similar, deep at heart, to a Makefile. Take sources, compile them into something, in this case a website. Instead of a Makefile, Nikola uses -`doit <http://pydoit.com>`_ +`doit <http://pydoit.org>`_ Doit has the concept of "tasks". The 1 minute summary of tasks is that they have: @@ -77,8 +85,8 @@ one of the existing ones. You can do doctests, you can do unit tests, you can do integration tests. There is support for all of them. -Post and Stories ----------------- +Posts and Stories +----------------- Nikola has a concept of posts and stories. Both are more or less the same thing, except posts are added into RSS feeds and stories are not. All of them are in a list called @@ -100,17 +108,19 @@ the timeline, because it will cause consistency issues. Your plugin can use the timeline to generate "stuff" (technical term). For example, Nikola comes with plugins that use the timeline to create a website (surprised?). -The workflow included with nikola is as follows: +The workflow included with nikola is as follows (incomplete!): -#. The post is assigned a compiler based on its extension and the ``post_compilers`` option. +#. The post is assigned a compiler based on its extension and the ``COMPILERS`` option. #. The compiler is applied to the post data and a "HTML fragment" is produced. That - fragment is stored in a cache (the ``render_posts`` plugin). + fragment is stored in a cache (the ``posts`` plugin). #. The configured theme has templates (and a template engine), which are applied to the post's - HTML fragment and metadata (the ``render_pages`` plugin). -#. The original sources for the post are copied to some accessible place (the ``render_sources`` plugin) -#. If the post is tagged, some pages and RSS feeds for each tag are updated (the ``render_tags`` plugin) -#. If the post is new, it's included in the blog's RSS feed (the ``render_rss`` plugin) -#. The post is added in the right place in the index pages for the blog (the ``task_indexes`` plugin) + HTML fragment and metadata (the ``pages`` plugin). +#. The original sources for the post are copied to some accessible place (the ``sources`` plugin) +#. If the post is tagged, some pages and RSS feeds for each tag are updated (the ``tags`` plugin) +#. If the post is new, it's included in the blog's RSS feed (the ``rss`` plugin) +#. The post is added in the right place in the index pages for the blog (the ``indexes`` plugin) +#. CSS/JS/Images for the theme are put in the right places (the ``copy_assets`` and ``bundles`` plugins) +#. A File describing the whole site is created (the ``sitemap`` plugin) You can add whatever you want to that list: just create a plugin for it. @@ -128,4 +138,3 @@ themes To change how the generated site looks, you can create custom themes. And of course, you can also replace or extend each of the existing plugins. - diff --git a/docs/man/nikola.1 b/docs/man/nikola.1 index 8f77039..9385a2a 100644 --- a/docs/man/nikola.1 +++ b/docs/man/nikola.1 @@ -1,60 +1,88 @@ -====== -nikola -====== - --------------------------------- -A Static Site and Blog Generator --------------------------------- - -:Manual section: 1 -:Manual group: nikola - -SYNOPSIS -======== - -**nikola** command [*options*] - - -DESCRIPTION -=========== - -nikola - is a simple yet powerful and flexible static website and blog generator - -OPTIONS -======= - -bootswatch_theme - Given a swatch name and a parent theme, creates a custom theme. - -build - Build the site. - -check - Check the generated site - -deploy - Deploy the site - -import_wordpress - Import a wordpress site from a XML dump (requires markdown). - -init - Create a new site. - -install_theme - Install a theme into the current site. - -new_post - Create a new post. - -serve - Start test server. - -command --help - Get detailed help for a command - -AUTHOR -====== - -Roberto Alsina <http://ralsina.com.ar/> +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.43.3. +.TH NIKOLA "1" "November 2013" "nikola 6.2.1" "User Commands" +.SH NAME +nikola \- manual page for nikola 6.2.1 +.SH DESCRIPTION +Nikola is a tool to create static websites and blogs. For full documentation and more information, please visit http://getnikola.com +.SS "Available commands:" +.TP +nikola auto +automatically detect site changes, rebuild and optionally refresh a browser +.TP +nikola bootswatch_theme +given a swatch name from bootswatch.com and a parent theme, creates a custom theme +.TP +nikola build +run tasks +.TP +nikola check +check links and files in the generated site +.TP +nikola clean +clean action / remove targets +.TP +nikola console +Start an interactive Python (IPython\->bpython\->plain) console with access to your site and configuration +.TP +nikola deploy +deploy the site +.TP +nikola dumpdb +dump dependency DB +.TP +nikola forget +clear successful run status from internal DB +.TP +nikola help +show help +.TP +nikola ignore +ignore task (skip) on subsequent runs +.TP +nikola import_blogger +import a blogger dump +.TP +nikola import_feed +import a RSS/Atom dump +.TP +nikola import_wordpress +import a WordPress dump +.TP +nikola init +create a Nikola site in the specified folder +.TP +nikola install_plugin +install plugin into current site +.TP +nikola install_theme +install theme into current site +.TP +nikola list +list tasks from dodo file +.TP +nikola mincss +apply mincss to the generated site +.TP +nikola new_post +create a new blog post or site page +.TP +nikola run +run tasks +.TP +nikola serve +start the test webserver +.TP +nikola strace +use strace to list file_deps and targets +.TP +nikola version +print the Nikola version number +.TP +nikola help +show help / reference +.TP +nikola help <command> +show command usage +.TP +nikola help <task\-name> +show task usage diff --git a/docs/manual.txt b/docs/manual.txt index 4833eae..c186260 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -1,7 +1,14 @@ +.. title: The Nikola Handbook +.. slug: handbook +.. date: 2012/03/30 23:00 +.. tags: +.. link: +.. description: + The Nikola Handbook =================== -:Version: 5.4.4 +:Version: 6.2.1 .. class:: alert alert-info pull-right @@ -11,7 +18,7 @@ The Nikola Handbook All You Need to Know -------------------- -After you have Nikola installed: +After you have Nikola `installed <#installing-nikola>`_: Create a empty site: ``nikola init mysite`` @@ -57,10 +64,10 @@ instead of something the user generates. Nikola can do: -* A blog (`example <http://lateral.netmanagers.com.ar>`__) +* A blog (`example <http://ralsina.me>`__) * Your company's site * Your personal site -* A software project's site (`example <http://nikola.ralsina.com.ar>`__) +* A software project's site (`example <http://getnikola.com>`__) * A book's site Since Nikola-based sites don't run any code on the server, there is no way to process @@ -71,7 +78,7 @@ Nikola can't do: * Twitter * Facebook * An Issue tracker -* Anything with forms, really (except for comments_!) +* Anything with forms, really (except for `comments <#comments-and-annotations>`_!) 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 @@ -83,10 +90,10 @@ Getting Help ------------ * Feel free to contact me at ralsina@netmanagers.com.ar for questions about Nikola. -* You can file bugs at `the issue tracker <https://github.com/ralsina/nikola-site/issues>`__ +* You can file bugs at `the issue tracker <https://github.com/getnikola/nikola/issues>`__ * 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>`_ +* You can subscribe to `the Nikola Blog <http://getnikola.com/blog>`_ +* You can follow `Nikola on Twitter <https://twitter.com/nikolagenerator>`_ Why Static? ----------- @@ -106,13 +113,13 @@ 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). + like those Nikola generates, is much smaller (Just a web server). 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, + 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. @@ -142,7 +149,7 @@ Cost and Performance 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, + blogging platforms from Advogato to PyCs to two homebrew 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. @@ -151,7 +158,7 @@ Lockin Features -------- -Nikola has a very defined featureset: it has every feature I needed for my own sites. +Nikola has a very defined feature set: 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: @@ -168,7 +175,7 @@ If you want to create a blog or a site, Nikola provides: * 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 +* The input format is light markup (`reStructuredText <quickstart.html>`__ or `Markdown <http://daringfireball.net/projects/markdown/>`_) * Easy-to-create image galleries * Support for displaying source code @@ -177,7 +184,7 @@ If you want to create a blog or a site, Nikola provides: Also: -* A preview webserver +* A preview web server * "Live" re-rendering while you edit * "Smart" builds: only what changed gets rebuilt (usually in seconds) * Easy to extend with minimal Python knowledge. @@ -189,28 +196,40 @@ 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/archive/master.zip`` +The short version is: ``pip install nikola`` + +Note that you need Python v2.6 or newer OR v3.3 or newer. + +For some features it may give you an error message telling you that you need to +install something else. For example, if it tells you you need ``requests``:: + + pip install requests + +And so on. Longer version: -#. Get `Nikola <http://nikola.ralsina.com.ar/>`_ +#. Get `Nikola <http://getnikola.com/>`_ #. Install dependencies. To do that, either: - #. ``pip install -r requirements.txt`` and ``pip install .`` or... + #. ``pip install -r requirements.txt`` (or ``requirements-full.txt`` + for extra stuff) and ``pip install .`` or... #. Install your distribution's packages for all the things mentioned below, if they exist, or... #. Get all of these manually (but why?, use pip): - #. Get python, if you don't have it. + #. Get Python, if you don't have it. #. Get `doit <http://pydoit.org>`_ #. Get `docutils <http://docutils.sf.net>`_ #. Get `Mako <http://makotemplates.org>`_ - #. Get `PIL <http://www.pythonware.com/products/pil/>`_ (or Pillow) + #. Get `Pillow <http://python-imaging.github.io/>`_ #. Get `Pygments <http://pygments.org/>`_ #. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ #. Get `lxml <http://lxml.de/>`_ #. Get `yapsy <http://yapsy.sourceforge.net>`_ - #. Get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_ + #. Get `PyRSS2Gen <http://www.dalkescientific.com/Python/PyRSS2Gen.html>`_ + #. Get `pytz <http://pytz.sourceforge.net/>`_ + #. If using Python 2, get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_ #. run ``python setup.py install`` @@ -222,33 +241,65 @@ Nikola is packaged for some Linux distributions, you may get that instead. *NOTE*: If you get a ``ERROR: /bin/sh: 1: xslt-config: not found`` or ``fatal error: libxml/xmlversion.h: No such file or directory`` when running ``pip install -r requirements.txt``, install *libxml* and *libxslt* libraries, like so: -Debian systems: +Debian systems:: sudo apt-get install libxml2-dev sudo apt-get install libxslt1-dev -RHEL systems: +Red Hat/RPM based systems:: yum install libxslt-devel libxml2-devel +Installation on Linux, Mac OS X, \*BSD, and any other POSIX-compatible OS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +(we obviously support all.) + +Using ``pip`` should suffice. You may also want to use distribution- or +system-specific packages for our dependencies. + +There are **no known issues or caveats** on those OSes. Keep in mind that most +of our developers run Linux on a daily basis and may not have the full +knowledge required to resolve issues relating to your operating system. + +Installation on Windows and Windows support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nikola supports Windows! Keep in mind, though, that there are some +caveats: + +1. ``lxml`` and ``Pillow`` require compiled extensions. Compiling them on +Windows is hard for most people. Fortunately, compiled packages exist. Check +their `PyPI <https://pypi.python.org/>`_ pages to find official packages, `the unofficial Gohlke binaries <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ site, or get them somewhere else. If you are using virtualenvs, using those pre-built packages is possible through ``virtualenv --system-site-packages``. +2. Windows has some differences over POSIX, which may cause some features to work incorrectly under Windows. If any problems occur, please do not hesitate to report them. Some of the differeces include: + + * ``\`` as path separator (instead of ``/``) + * the concept of partitions + * some characters in paths are disallowed (although this shouldn’t cause + problems) + * CR+LF (aka ``\r\n``) as the line separator (instead of LF ``\n``) + +3. Windows also dislikes some characters in paths. +4. Most of our developers run Linux on a daily basis and may not have the full knowledge required to resolve issues relating to Windows. + Getting Started --------------- To create posts and pages in Nikola, you write them in one of the supported input formats. Those source files are later converted to HTML -The recommended formats are restructured text and Markdown, but there is also support +The recommended formats are reStructuredText and Markdown, but there is also support for textile and WikiCreole and even for just writing HTML. -.. note:: There is a great `quick tutorial to learn restructured text. <quickstart.html>`_ +.. note:: There is a great `quick tutorial to learn reStructuredText. <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://pydoit.org>`_, and it rebuilds the +The tool used to do builds is called `doit <http://pydoit.org>`__, 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 "nikola build":: $ nikola build - Scanning posts . . done! + Scanning posts....done! . render_posts:stories/manual.html . render_posts:posts/1.html . render_posts:stories/1.html @@ -260,17 +311,17 @@ first build, just run "nikola build":: . 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:: $ nikola build - Scanning posts . . done! + Scanning posts....done! -That is because `doit <http://pydoit.org>`_ is smart enough not to generate +That is because `doit <http://pydoit.org>`__ 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. @@ -278,7 +329,7 @@ will be recreated. If you change the post page template, then all the post pages Nikola is mostly a series of doit *tasks*, and you can see them by doing ``nikola list``:: $ nikola list - Scanning posts . . done! + Scanning posts....done! build_bundles copy_assets copy_files @@ -296,39 +347,46 @@ Nikola is mostly a series of doit *tasks*, and you can see them by doing ``nikol render_tags sitemap -You can make Nikola redo everything by calling ``nikola build forget``, you can make it do just a specific -part of the site using task names, for example ``nikola build render_pages``, and even individual files like -``nikola build render_indexes:output/index.html`` +You can make Nikola redo everything by calling ``nikola forget`` and then ``nikola build`` (or ``nikola build -a``, +you can make it do just a specific part of the site using task names, for example ``nikola build render_pages``, +and even individual files like ``nikola build output/index.html`` Nikola also has other commands besides ``build``:: $ nikola help - Nikola - Available commands: - nikola auto automatically execute tasks when a dependency changes - nikola bootswatch_theme Given a swatch name and a parent theme, creates a custom theme. - nikola build run tasks - nikola check Check links and files in the generated site. - nikola clean clean action / remove targets - nikola console A short explanation. - nikola deploy Deploy the site. - nikola dumpdb dump dependency DB - nikola forget clear successful run status from internal DB - nikola help show help - nikola ignore ignore task (skip) on subsequent runs - nikola import_blogger Import a blogger dump. - nikola import_wordpress Import a wordpress dump. - nikola init Create a Nikola site in the specified folder. - nikola install_theme Install theme into current site. - nikola list list tasks from dodo file - nikola new_post Create a new blog post or site page. - nikola run run tasks - nikola serve Start the test webserver. - nikola strace use strace to list file_deps and targets - - nikola help show help / reference - nikola help <command> show command usage - nikola help <task-name> show task usage + Nikola is a tool to create static websites and blogs. For full documentation and more information, + please visit http://getnikola.com + + + Available commands: + nikola auto automatically detect site changes, rebuild and optionally refresh a browser + nikola bootswatch_theme given a swatch name from bootswatch.com and a parent theme, creates a custom theme + nikola build run tasks + nikola check check links and files in the generated site + nikola clean clean action / remove targets + nikola console start an interactive python console with access to your site and configuration + nikola deploy deploy the site + nikola dumpdb dump dependency DB + nikola forget clear successful run status from internal DB + nikola help show help + nikola ignore ignore task (skip) on subsequent runs + nikola import_blogger import a blogger dump + nikola import_feed import a RSS/Atom dump + nikola import_wordpress import a WordPress dump + nikola init create a Nikola site in the specified folder + nikola install_theme install theme into current site + nikola list list tasks from dodo file + nikola mincss apply mincss to the generated site + nikola new_post create a new blog post or site page + nikola run run tasks + nikola serve start the test webserver + nikola strace use strace to list file_deps and targets + nikola version print the Nikola version number + + nikola help show help / reference + nikola help <command> show command usage + nikola help <task-name> show task usage + The ``serve`` command starts a web server so you can see the site you are creating:: @@ -340,7 +398,7 @@ After you do this, you can point your web browser to http://localhost:8000 and y the sample site. This is useful as a "preview" of your work. By default, the ``serve`` command 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`` +You can pass in an IP address and port number explicitly using ``-a IP_ADDRESS`` (short version of ``--address``) or ``-p PORT_NUMBER`` (short version of ``--port``) Example usage:: @@ -358,14 +416,14 @@ By default, that file will contain also some extra information about your post ( It can be placed in a separate file by using the ``-2`` option, but it's generally easier to keep it in a single location. -The contents of your post have to be written (by default) in `restructured text <http://docutils.sf.net>`_ +The contents of your post have to be written (by default) in `reStructuredText <http://docutils.sf.net>`__ but you can use a lot of different markups using the ``-f`` option. Currently Nikola supports bbcode, wiki, markdown, html, txt2tags and textile in addition -to restructured text. +to reStructuredText. -You can control what markup compiler is used for each file extension with the ``post_compilers`` +You can control what markup compiler is used for each file extension with the ``COMPILERS`` option. The default configuration expects them to be placed in ``posts`` but that can be -changed (see below, the post_pages option) +changed (see below, the ``POSTS`` and ``PAGES`` options) This is how it works:: @@ -387,7 +445,7 @@ The content of that file is as follows:: Write your post here. -The ``slug`` is the pagename. Since often titles will have +The ``slug`` is the page name. 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". @@ -397,6 +455,15 @@ source for the content, and ``description`` is mostly useful for SEO. You can add your own metadata fields in the same manner, if you use a theme that supports them (for example: ``.. author: John Doe``) +To add these metadata fields to all new posts by default, you can set the +variable ``ADDITIONAL_METADATA`` in your configuration. For example, you can +add the author metadata to all new posts by default, by adding the following +to your configuration :: + + ADDITIONAL_METADATA = { + 'author': 'John Doe' + } + .. sidebar:: Other Metadata Fields Nikola will also use other metadata fields: @@ -411,10 +478,28 @@ supports them (for example: ``.. author: John Doe``) .. template: story.tmpl + That template needs to either be part of the theme, or be placed in a ``templates/`` + folder inside your site. + password The post will be encrypted and invisible until the reader enters the password. Also, the post's sourcecode will not be available. + category + Like tags, except each post can have only one, and they usually have + more descriptive names. + + annotations / noannotations + Override the value of the ``ANNOTATIONS`` option for this specific post or page. + + author + Author of the post, will be used in the RSS feed and possibly in the post + display (theme-dependent) + + hidetitle + Set "True" if you do not want to see the **story** title as a + heading of the page (does not work for posts). + .. note:: The Two-File Format @@ -431,7 +516,7 @@ post file (for example: ``how-to-make-money.txt.es``). This one can replace metadata of the default language, for example: * The translated title for the post or page -* A translated version of the pagename +* A translated version of the page name 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`_ @@ -450,19 +535,21 @@ Currently supported languages are * Spanish If you wish to add support for more languages, check out the instructions -at the `theming guide <http://nikola.ralsina.com.ar/theming.html>`_. +at the `theming guide <http://getnikola.com/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:: +The place where the post will be placed by ``new_post`` is based on the ``POSTS`` +and ``PAGES`` configuration options:: - # post_pages contains (wildcard, destination, template, use_in_feed) tuples. + # POSTS and PAGES contains (wildcard, destination, template) tuples. + # + # The wildcard is used to generate a list of reSt source files + # (whatever/thing.txt). # - # 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"): + # That fragment could have an associated metadata file (whatever/thing.meta), + # and optionally 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: @@ -472,18 +559,24 @@ configuration option:: # pages, which will be placed at # output / TRANSLATIONS[lang] / destination / pagename.html # - # where "pagename" is specified in the metadata file. + # where "pagename" is the "slug" specified in the metadata file. # - # if use_in_feed is True, then those posts will be added to the site's - # rss feeds. + # The difference between POSTS and PAGES is that POSTS are added + # to feeds and are considered part of a blog, while PAGES are + # just independent HTML pages. # - post_pages = ( - ("posts/*.txt", "posts", "post.tmpl", True), - ("stories/*.txt", "stories", "story.tmpl", False), + + POSTS = ( + ("posts/*.txt", "posts", "post.tmpl"), + ("posts/*.rst", "posts", "post.tmpl"), + ) + PAGES = ( + ("stories/*.txt", "stories", "story.tmpl"), + ("stories/*.rst", "stories", "story.tmpl"), ) -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. +It will use the first location that has the last item in ``POSTS``, or the last +one in ``PAGES`` if ``POSTS`` is empty. The ``new_post`` command supports some options:: @@ -511,7 +604,7 @@ index page or in RSS feeds, but to display instead only the beginning of them. If it's the case, you only need to add a "magical comment" in your post. -In restructuredtext:: +In reStructuredText:: .. TEASER_END @@ -530,12 +623,32 @@ change that text, you can use a custom teaser:: .. TEASER_END: click to read the rest of the article +Or you can completely customize the link using the ``READ_MORE_LINK`` option:: + + # A HTML fragment with the Read more... link. + # The following tags exist and are replaced for you: + # {link} A link to the full post page. + # {read_more} The string “Read more” in the current language. + # {{ A literal { (U+007B LEFT CURLY BRACKET) + # }} A literal } (U+007D RIGHT CURLY BRACKET) + # READ_MORE_LINK = '<p class="more"><a href="{link}">{read_more}…</a></p>' + + 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. +with care. If you wish your drafts to be not available in your deployed site, you +can set ``DEPLOY_DRAFTS = False`` in your configuration. + +Also if a post has a date in the future, it will not be shown in indexes until +you rebuild after that date. This behaviour can be disabled by setting +``FUTURE_IS_NOW = True`` in your configuration, which will make future posts be +published immediately. Posts dated in the future are *not* deployed by default +(when ``FUTURE_IS_NOW = False``). To make future posts available in the +deployed site, you can set ``DEPLOY_FUTURE = True`` in your configuration. +Generally, you want FUTURE_IS_NOW and DEPLOY_FUTURE to be the same value. Retired Posts ~~~~~~~~~~~~~ @@ -544,6 +657,57 @@ If you add a "retired" tag to a post, then it will not be shown in indexes and f It *will* be compiled, and if you deploy it it *will* be made available, so it will not generate 404s for people who had linked to it. +Queuing Posts +~~~~~~~~~~~~~ + +Some blogs tend to have new posts based on a schedule (for example, +every Mon, Wed, Fri) but the blog authors don't like to manually +schedule their posts. You can schedule your blog posts based on a +rule, by specifying a rule in the ``SCHEDULE_RULE`` in your +configuration. You can either post specific blog posts according to +this schedule by using the ``--schedule`` flag on the ``new_post`` +command or post all new posts according to this schedule by setting +``SCHEDULE_ALL = True`` in your configuration. (Note: This feature +requires that the ``FUTURE_IS_NOW`` setting is set to ``False``) + +For example, if you would like to schedule your posts to be on every +Monday, Wednesday and Friday at 7am, add the following +``SCHEDULE_RULE`` to your configuration :: + + SCHEDULE_RULE = 'RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=7;BYMINUTE=0;BYSECOND=0' + +For more details on how to specify a recurrence rule, look at the +`iCal specification <http://www.kanzaki.com/docs/ical/rrule.html>`_. + +Say, you get a free Sunday, and want to write a flurry of new posts, +or at least posts for the rest of the week, you would run the +``new_post`` command with the ``--schedule`` flag, as many times as +you want:: + + $ nikola new_post --schedule + # Creates a new post to be posted on Monday, 7am. + $ nikola new_post -s + # Creates a new post to be posted on Wednesday, 7am. + $ nikola new_post -s + # Creates a new post to be posted on Friday, 7am. + . + . + . + +All these posts get queued up according to your schedule, but note +that you will anyway need to build and deploy your site for the posts +to appear online. You can have a cron job that does this regularly. + +An additional setting (``SCHEDULE_FORCE_TODAY = True``) lets you tell +Nikola to make the post today, if you run the ``new_post --schedule`` +after the scheduled hour has passed, and there is no other post +at/after the scheduled hour. Concretely, say, you run the ``nikola +new_post -s`` command at 10am on a Monday (with the schedule rule set +to the same as above), with no other post on Monday, at/after 7am, +setting ``SCHEDULE_FORCE_TODAY = True`` will have your post scheduled +to Monday, instead of being scheduled to Wednesday 7am. + + Creating a Page --------------- @@ -554,10 +718,10 @@ Pages are the same as posts, except that: * 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). +``stories`` folder, but that can be changed (see ``PAGES`` option above). You can create the page's files manually or use the ``new_post`` command -with the ``-p`` option, qhich will place the files in the folder that +with the ``-p`` option, which will place the files in the folder that has ``use_in_feed`` set to False. Redirections @@ -587,15 +751,13 @@ 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>`_) +commented. You surely want to edit these options:: # Data about this site BLOG_TITLE = "Demo Site" - SITE_URL = "http://nikola.ralsina.com.ar" + SITE_URL = "http://getnikola.com" BLOG_EMAIL = "joe@demo.site" BLOG_DESCRIPTION = "This is a demo site for Nikola." @@ -611,18 +773,35 @@ CSS tweaking 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>`_. + 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>`_. + `custom theme <theming.html>`__. -Sidebar - ``LICENSE`` is a HTML snippet for things like a CC badge, or whatever you prefer. +Navigation Links + The 'NAVIGATION_LINKS' option lets you define what links go in a sidebar or menu + (depending on your theme) so you can link to important pages, or to other sites. + + The format is a language-indexed dictionary, where each element is a tuple of + tuples which are one of: + + 1. A (url, text) tuple, describing a link + 2. A ((url, text), (url, text), (url, text), title) tuple, describing a submenu / sublist. + + Example:: + + NAVIGATION_LINKS = { + DEFAULT_LANG: ( + ('/archive.html', 'Archives'), + ('/categories/index.html', 'Tags'), + ('/rss.xml', 'RSS'), + ((('/foo', 'FOO'), + ('/bar', 'BAR')), 'BAZ'), + ), + } - 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 @@ -630,20 +809,24 @@ Sidebar Footer ``CONTENT_FOOTER`` is displayed, small at the bottom of all pages, I use it for - the copyright notice. + the copyright notice. The default shows a text formed using ``BLOG_AUTHOR``, + ``BLOG_EMAIL``, the date and ``LICENSE``. -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. +BODY_END + This 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. Good place for JavaScript. +SOCIAL_BUTTONS_CODE + The ``SOCIAL_BUTTONS_CODE`` option lets you define a HTML snippet that will be added + at the bottom of body. It defaults to a snippet for AddThis, but you can + really put anything there. See `social_buttons.html` for more details. 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 +``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). @@ -664,36 +847,41 @@ change the FILES_FOLDERS option:: 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`` command:: +There are a few themes for Nikola. They are available at +the `Themes Index <http://themes.getnikola.com/>`_. +Nikola has a built-in theme download/install mechanism to install those themes — the ``install_theme`` command:: $ nikola install_theme -l Themes: ------- + base-jinja blogtxt - readable + ⋮ + ⋮ - $ nikola install_theme -n blogtxt - Downloading: http://nikola.ralsina.com.ar/themes/blogtxt.zip - Extracting: blogtxt into themes + $ nikola install_theme blogtxt + [2013-10-12T16:46:13Z] NOTICE: install_theme: Downloading: + http://themes.getnikola.com/v6/blogtxt.zip + [2013-10-12T16:46:15Z] NOTICE: install_theme: 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. +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. +If you create a nice theme, please share it! You can do it as a pull +request in the `GitHub repository <https://github.com/getnikola/nikola-themes>`__. 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:: - $ nikola bootswatch_theme -n custom_theme -s spruce -p site - 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. + $ nikola bootswatch_theme -n custom_theme -s spruce -p bootstrap3 + [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Creating 'custom_theme' theme + from 'spruce' and 'bootstrap3' + [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: + http://bootswatch.com//spruce/bootstrap.min.css + [2013-10-12T16:46:58Z] NOTICE: bootswatch_theme: Downloading: + http://bootswatch.com//spruce/bootstrap.css + [2013-10-12T16:46:59Z] NOTICE: bootswatch_theme: 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>`_ @@ -714,26 +902,53 @@ 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', + 'rdiff-backup output ~/blog-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 +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 --------- +Comments and Annotations +------------------------ 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. +Nikola supports several third party comment systems: + +* `DISQUS <http://disqus.com>`_ +* `IntenseDebate <http://www.intensedebate.com/>`_ +* `LiveFyre <http://www.livefyre.com/>`_ +* `Moot <http://moot.it>`_ +* `Google+ <http://plus.google.com>`_ +* `Facebook <http://facebook.com>`_ + +By default it will use DISQUS, but you can change by setting ``COMMENT_SYSTEM`` +to one of "disqus", "intensedebate", "livefyre", "moot", "googleplus" or +"facebook" -Disqus is a good option because: +.. sidebar:: ``COMMENT_SYSTEM_ID`` + + The value of ``COMMENT_SYSTEM_ID`` depends on what comment system you + are using and you can see it in the system's admin interface. + + * For DISQUS it's called the **shortname** + * In IntenseDebate it's the **IntenseDebate site acct** + * In LiveFyre it's the **siteId** + * In Moot it's your **username** + * For Google Plus, ``COMMENT_SYSTEM_ID`` need not be set, but you must + `verify your authorship <https://plus.google.com/authorship>`_ + * For Facebook, you need to `create an app + <https://developers.facebook.com/apps>` (turn off sandbox mode!) + and get an **App ID** + +To use comments in a visible site, you should register with the service and +then set the ``COMMENT_SYSTEM_ID`` option. + +I recommend 3rd party comments, and specially DISQUS 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 @@ -745,12 +960,44 @@ You can disable comments for a post by adding a "nocomments" metadata field to i .. nocomments: True -.. admonition:: Important +.. admonition:: DISQUS Support 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. +.. admonition:: Moot Support + + Moot doesn't support comment counts on index pages, and it requires adding + this to your ``conf.py``: + + .. code-block:: python + + BODY_END = """ + <script src="//cdn.moot.it/1/moot.min.js"></script> + """ + EXTRA_HEAD_DATA = """ + <link rel="stylesheet" type="text/css" href="//cdn.moot.it/1/moot.css"> + <meta name="viewport" content="width=device-width"> + <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> + """ + +.. admonition:: Facebook Support + + You need jQuery, but not because Facebook wants it (see Issue + #639). + +An alternative or complement to comments are annotations. Nikola integrates +the annotation service provided by `AnnotateIt. <annotateit.org>`_ +To use it, set the ``ANNOTATIONS`` option to True. This is specially useful +if you want feedback on specific parts of your writing. + +You can enable or disable annotations for specific posts or pages using the +``annotations`` and ``noannotations`` metadata. + +Annotations require JQuery and are therefore not supported in the base theme. +You can check bootstrap theme's ``base.html`` for details on how to handle them in +custom themes. Image Galleries --------------- @@ -773,9 +1020,12 @@ The ``conf.py`` options affecting gallery pages are these:: THUMBNAIL_SIZE = 180 MAX_IMAGE_SIZE = 1280 USE_FILENAME_AS_TITLE = True + GALLERY_SORT_BY_DATE = False + EXTRA_IMAGE_EXTENSIONS = [] 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. +converted to HTML and inserted above the images in the gallery page. The +format is the same as for posts. If you add some image filenames in ``galleries/gallery_name/exclude.meta``, they will be excluded in the gallery page. @@ -809,12 +1059,55 @@ replace that with strings describing command lines, or arbitrary python function 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. +The currently available filters are: + +.. sidebar:: Creating your own filters + + You can use any program name that works in place as a filter, like ``sed -i`` + and you can use arbitrary python functions as filters, too. + + If your program doesn't run in-place, then you can use Nikola's runinplace function. + For example, this is how the yui_compressor filter is implemented: + + .. code-block:: python + + def yui_compressor(infile): + return runinplace(r'yui-compressor --nomunge %1 -o %2', infile) + + You can turn any function into a filter using ``apply_to_file``. + As a silly example, this would make everything uppercase and totally break + your website: + + .. code-block:: python + + import string + from nikola.filters import apply_to_file + FILTERS = { + ".html": [apply_to_file(string.upper)] + } + +yui_compressor + Compress files using `YUI compressor <http://yui.github.io/yuicompressor/>`_ + +optipng + Compress PNG files using `optipng <http://optipng.sourceforge.net/>`_ + +jpegoptim + Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_ + +tidy + Apply `tidy <http://tidy.sourceforge.net/>`_ to HTML files + +typogrify + Improve typography using `typogrify <https://github.com/mintchaos/typogrify>`_ + + 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! +different ones, or about other web servers, 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. @@ -833,21 +1126,33 @@ different ones, or about other webservers, please share! #. The webassets Nikola plugin can drastically decrease the number of CSS and JS files your site fetches. #. Through the filters feature, you can run your files through arbitrary commands, so that images - are recompressed, Javascript is minimized, etc. + are recompressed, JavaScript is minimized, etc. -#. The USE_CDN option offloads standard Javascript and CSS files to a CDN so they are not +#. The USE_CDN option offloads standard JavaScript and CSS files to a CDN so they are not downloaded from your server. -Restructured Text Extensions ----------------------------- +reStructuredText Extensions +--------------------------- -Nikola includes support for a few directives that are not part of docutils, but which +Nikola includes support for a few directives and roles that are not part of docutils, but which we think are handy for website development. -Youtube +Media +~~~~~ + +This directive lets you embed media from a variety of sites automatically by just passing the +URL of the page. For example here are two random videos:: + + .. media:: http://vimeo.com/72425090 + + .. youtube:: http://www.youtube.com/watch?v=wyRpAat5oz0 + +It supports Instagram, Flickr, Github gists, Funny or Die, and dozens more, thanks to `Micawber <https://github.com/coleifer/micawber>`_ + +YouTube ~~~~~~~ -To link to a youtube video, you need the id of the video. For example, if the +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** @@ -858,15 +1163,14 @@ Once you have that, all you need to do is:: Vimeo ~~~~~ -To link to a vimeo video, you need the id of the video. For example, if the +To link to a Vimeo video, you need the id of the video. For example, if the URL of the video is http://www.vimeo.com/20241459 then the id is **20241459** Once you have that, all you need to do is:: .. vimeo:: 20241459 -If you are running python 2.6 or later, or have the json module installed and -have internet connectivity when generating your site, the height and width of +If you have internet connectivity when generating your site, the height and width of the embedded player will be set to the native height and width of the video. You can override this if you wish:: @@ -879,7 +1183,7 @@ Soundcloud This directive lets you share music from http://soundcloud.com You first need to get the ID for the piece, which you can find in the "share" link. For example, if the -Wordpress code starts like this:: +WordPress code starts like this:: [soundcloud url="http://api.soundcloud.com/tracks/78131362" @@ -894,7 +1198,7 @@ The ``code`` directive has been included in docutils since version 0.9 and now replaces Nikola's ``code-block`` directive. To ease the transition, two aliases for ``code`` directive are provided: ``code-block`` and ``sourcecode``:: - .. code:: python + .. code-block:: python :number-lines: print("Our virtues and our failings are inseparable") @@ -936,7 +1240,7 @@ Producing this: .. gist:: 2395294 -This degrades gracefully if the browser doesn't support javascript. +This degrades gracefully if the browser doesn't support JavaScript. Slideshows ~~~~~~~~~~ @@ -951,17 +1255,65 @@ To create an image slideshow, you can use the ``slides`` directive. For example: /galleries/demo/tesla_lightning1_lg.jpg /galleries/demo/tesla_tower1_lg.jpg +Chart +~~~~~ + +This directive is a thin wrapper around `Pygal <http://pygal.org/>`_ and will produce charts +as SVG files embedded directly in your pages. + +Here's an example of how it works:: + + .. chart:: Bar + :title: 'Browser usage evolution (in %)' + :x_labels: ["2002", "2003", "2004", "2005", "2006", "2007"] + + 'Firefox', [None, None, 0, 16.6, 25, 31] + 'Chrome', [None, None, None, None, None, None] + 'IE', [85.8, 84.6, 84.7, 74.5, 66, 58.6] + 'Others', [14.2, 15.4, 15.3, 8.9, 9, 10.4] + +The argument passed next to the directive (Bar in that example) is the type of chart, and can be one of +Line, StackedLine, Bar, StackedBar, HorizontalBar, XY, DateY, Pie, Radar, Dot, Funnel, Gauge, Pyramid. For +examples of what each kind of graph is, `check here <http://pygal.org/chart_types/>`_ -Importing Your Wordpress Site Into Nikola +It can take *a lot* of options to let you customize the charts (in the example, title and x_labels). +You can use any option described in `the pygal docs <http://pygal.org/basic_customizations/>`_ + +Finally, the content of the directive is the actual data, in the form of a label and +a list of values, one series per line. + +Doc +~~~ + +This role is useful to make links to other post or page inside the same site. + +Here's an example:: + + Take a look at :doc:`my other post <creating-a-theme>` about theme creating. + +In this case we are giving the portion of text we want to link. So, the result will be: + + Take a look at :doc:`my other post <creating-a-theme>` about theme creating. + +If we want to use the post's title as the link's text, just do:: + + Take a look at :doc:`creating-a-theme` to know how to do it. + +and it will produce: + + Take a look at :doc:`creating-a-theme` to know how to do it. + + +Importing Your WordPress Site Into Nikola ----------------------------------------- -If you like Nikola, and want to start using it, but you have a Wordpress blog, 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 -f mysite.wordpress.2012-12-20.xml +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 +After some time, this will create a ``new_site`` folder with all your data. It currently supports the following: * All your posts and pages @@ -971,11 +1323,11 @@ the following: * 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! + 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. + WordPress uses some unholy mix of HTML and strange things. Currently we are treating it + as markdown, which does a reasonable 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. @@ -987,7 +1339,7 @@ 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. + WordPress before dumping. Other versions may or may not work. @@ -997,7 +1349,7 @@ Importing To A Custom Location Or Into An Existing Site It is possible to either import into a location you desire or into an already existing Nikola site. To do so you can specify a location after the dump.:: - $ nikola import_wordpress -f mysite.wordpress.2012-12-20.xml -o import_location + $ nikola import_wordpress mysite.wordpress.2012-12-20.xml -o import_location With this command Nikola will import into the folder ``import_location``. @@ -1075,14 +1427,13 @@ when they try to open a post. Local Search ~~~~~~~~~~~~ -If you don't want to depend on google or duckduckgo to implement search for you, -or just want it to wok even if you are offline, enable this plugin and the +If you don't want to depend on Google or DuckDuckGo to implement search for you, +or just want it to work even if you are offline, enable this plugin and the search will be performed client side. This plugin implements a Tipue-based local search for your site. -To use it, copy task_localsearch.plugin and task_localsearch -into a plugins/ folder in your nikola site. +To use it, enable local_search in ENABLED_EXTRAS in your sites conf.py After you build your site, you will have several new files in assets/css and assets/js and a tipue_search.html that you can use as a basis for using this in your site. @@ -1092,14 +1443,14 @@ docs at http://www.tipue.com/search/ Tipue is under an MIT license (see MIT-LICENSE.txt) -Here's a set of example settings for conf.py that should work nicely with the "site" theme:: +Here's a set of example settings for conf.py that should work nicely with the "bootstrap" theme:: SEARCH_FORM = """ <span class="navbar-form pull-left"> <input type="text" id="tipue_search_input"> </span>""" - ANALYTICS = """ + BODY_END = """ <script type="text/javascript" src="/assets/js/tipuesearch_set.js"></script> <script type="text/javascript" src="/assets/js/tipuesearch.js"></script> <script type="text/javascript"> @@ -1118,6 +1469,9 @@ Here's a set of example settings for conf.py that should work nicely with the "s <div id="tipue_search_content" style="margin-left: auto; margin-right: auto; padding: 20px;"></div> """ + ENABLED_EXTRAS = [ 'local_search' ] + + The <div> in EXTRA_HEAD_DATA is a hack but it will migrate into the <body> of the documents thanks to magic, and will hold the search results after the user searches. @@ -1128,11 +1482,52 @@ This task gives you a ``mustache.html`` file which lets you access your whole blog without reloading the page, using client-side templates. Makes it much faster and modern ;-) +Custom Plugins +-------------- + +You can create your own plugins (see :doc:`extending`) and use them in your own +site by putting them in a ``plugins/`` folder. + + +Getting Extra Plugins +--------------------- + +If you want extra plugins, there is also the `Plugins Index <http://plugins.getnikola.com/>`_. + +Similarly to themes, there is a nice, built-in command to install them — +``install_plugin``: + + $ nikola install_plugin -l + Plugins: + -------- + helloworld + tags + ⋮ + ⋮ + + $ nikola install_plugin helloworld + [2013-10-12T16:51:56Z] NOTICE: install_plugin: Downloading: http://plugins.getnikola.com/v6/helloworld.zip + [2013-10-12T16:51:58Z] NOTICE: install_plugin: Extracting: helloworld into plugins + plugins/helloworld/requirements.txt + [2013-10-12T16:51:58Z] NOTICE: install_plugin: This plugin has Python dependencies. + [2013-10-12T16:51:58Z] NOTICE: install_plugin: Installing dependencies with pip... + ⋮ + ⋮ + [2013-10-12T16:51:59Z] NOTICE: install_plugin: Dependency installation succeeded. + [2013-10-12T16:51:59Z] NOTICE: install_plugin: This plugin has a sample config file. + Contents of the conf.py.sample file: + + # Should the Hello World plugin say “BYE” instead? + BYE_WORLD = False + + +You can also share plugins you created with the community! Visit the +`GitHub repository <https://github.com/getnikola/plugins>`__ to find out more. License ------- -Nikola is released under a `MIT license <https://github.com/ralsina/nikola/blob/master/LICENSE.txt>`_ which +Nikola is released under a `MIT license <https://github.com/getnikola/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/social_buttons.txt b/docs/social_buttons.txt new file mode 100644 index 0000000..efbf9df --- /dev/null +++ b/docs/social_buttons.txt @@ -0,0 +1,202 @@ +.. title: Alternative Social Buttons +.. slug: social_buttons +.. date: 2013/08/19 23:00 +.. tags: +.. link: +.. description: + +Using Alternative Social Buttons with Nikola +============================================ + +:Version: 6.2.1 + +.. class:: alert alert-info pull-right + +.. contents:: + + +The Default +----------- + +By Default, the themes provided with Nikola will add to your pages a "slide in" widget at +the bottom right of the page, provided by Addthis. This is the HTML code for that: + +.. code-block:: html + + <!-- Social buttons --> + <div id="addthisbox" class="addthis_toolbox addthis_peekaboo_style + addthis_default_style addthis_label_style addthis_32x32_style"> + <a class="addthis_button_more">Share</a> + <ul><li><a class="addthis_button_facebook"></a> + <li><a class="addthis_button_google_plusone_share"></a> + <li><a class="addthis_button_linkedin"></a> + <li><a class="addthis_button_twitter"></a> + </ul> + </div> + <script type="text/javascript" src="//s7.addthis.com/js/300/addthis_widget.js#pubid=ra-4f7088a56bb93798"></script> + <!-- End of social buttons --> + """ + +You can change that using the ``SOCIAL_BUTTONS_CODE`` option in your conf.py. In some cases, just +doing that will be enough but in others, it won't. This document tries to describe all the bits +involved in making this work correctly. + +Part 1: ``SOCIAL_BUTTONS_CODE`` + Social sharing services like addthis and others will provide you a HTML snippet. + If it is self-contained, then just setting ``SOCIAL_BUTTONS_CODE`` may be enough. + Try :-) + +Part 2: The theme + The ``SOCIAL_BUTTONS_CODE`` HTML fragment will be embedded *somewhere* by the theme. Whether that + is the correct place or not is not something the theme author can truly know, so it is possible that + you may have to tweak the ``base.html`` template to make it look good. + +Part 3: ``BODY_END`` and ``EXTRA_HEAD_DATA`` + Some social sharing code requires JS execution that depends on JQuery being available + (example: `SocialSharePrivacy <https://github.com/panzi/SocialSharePrivacy>`__). It's good + practice (and often, the only way that will work) to put those at the end of ``<BODY>``, + and one easy way to do that is to put them in ``BODY_END`` + + On the other hand, it's possible that it requires you to load some CSS files. + The right place for that is in the document's ``<HEAD>`` so they should be added + in ``EXTRA_HEAD_DATA`` + +Part 4: assets + For sharing code that doesn't rely on a social sharing service, you may need to add CSS, Image, or JS + files to your site + +ShareNice +--------- + +`Sharenice <http://sharenice.org>`__ is "written in order to provide social sharing features to +web developers and website administrators who wish to maintain and protect their users' privacy" +which sounds cool to me. + +Let's go step by step into integrating the hosted version of ShareNice into a Nikola site. + +For testing purposes, let's do it on a demo site:: + + $ nikola init --demo sharenice_test + A new site with example data has been created at sharenice_test. + See README.txt in that folder for more information. + $ cd sharenice_test/ + +To see what's going on, let's start Nikola in "auto mode". This should build the +site and open a web browser showing the default configuration, with the AddThis widget:: + + $ nikola auto -b + +First, let's add the HTML snippet that will show the sharing options. In your conf.py, set this, which +is the HTML code suggested by ShareNice: + +.. code-block:: python + + SOCIAL_BUTTONS_CODE = """<div id="shareNice" data-share-label="Share" + data-color-scheme="black" data-icon-size="32" data-panel-bottom="plain" + data-services="plus.google.com,facebook.com,digg.com,email,delicious.com,twitter.com" + style="float:right"></div>""" + + BODY_END = """<script src="http://graingert.co.uk/shareNice/code.js" + type="text/javascript"></script>""" + +And you should now see a sharing box at the bottom right of the page. + +Main problem remaining is that it doesn't really look good and integrated in the page layout. +I suggest changing the code to this which looks nicer, but still has some placement issues: + +.. code-block:: python + + SOCIAL_BUTTONS_CODE = """<div id="shareNice" data-share-label="Share" + data-color-scheme="black" data-icon-size="32" data-panel-bottom="plain" + data-services="plus.google.com,facebook.com,email,twitter.com" + style="position: absolute; left: 20px; top: 60px;"></div>""" + +If anyone comes up with a better idea of styling/placement, just let me know ;-) + +One bad bit of this so far is that you are now using a script from another site, and that +doesn't let Nikola perform as many optimizations to your page as it could. +So, if you really want to go the extra mile to save a few KB and round trips, you *could* +install your own copy from the `github repo <https://github.com/mischat/shareNice>`_ and +use that instead of the copy at sharenice.org. + +Then, you can create your own theme inheriting from the one you are using and add the CSS +and JS files from ShareNice into your ``bundles`` configuration so they are combined and +minified. + +SocialSharePrivacy +------------------ + +The Hard Way +~~~~~~~~~~~~ + +`SocialSharePrivacy <https://github.com/panzi/SocialSharePrivacy>`__ is "a jQuery plugin that +lets you add social share buttons to your website that don't allow the social sites to track +your users." Nice! + +Let's go step-by-step into integrating SocialSharePrivacy into a Nikola site. To improve +privacy, they recommend you not use the hosted service so we'll do it the hard way, by +getting and distributing everything in our own site. + +https://github.com/panzi/SocialSharePrivacy + +For testing purposes, let's do it on a demo site:: + + $ nikola init --demo ssp_test + A new site with example data has been created at ssp_test. + See README.txt in that folder for more information. + $ cd ssp_test/ + +To see what's going on, let's start Nikola in "auto mode". This should build the +site and open a web browser showing the default configuration, with the AddThis widget:: + + $ nikola auto -b + +Now, download `the current version <https://github.com/panzi/SocialSharePrivacy/archive/master.zip>`_ +and unzip it. You will have a ``SocialSharePrivacy-master`` folder with lots of stuff in it. + +First, we need to build it (this requires a working and modern uglifyjs, this may not be easy):: + + $ cd SocialSharePrivacy-master + $ sh build.sh -m gplus,twitter,facebook,mail -s "/assets/css/socialshareprivacy.css" -a off + +You will now have several files in a ``build`` folder. We need to bring them into the site:: + + $ cp -Rv SocialSharePrivacy-master/build/* files/ + $ cp -R SocialSharePrivacy-master/images/ files/assets/ + +Edit your ``conf.py``: + +.. code-block:: python + + BODY_END = """ + <script type="text/javascript" src="/javascripts/jquery.socialshareprivacy.min.js"></script> + <script type="text/javascript"> + $(document).ready(function () { + $('.share').socialSharePrivacy(); + }); + </script> + """ + + SOCIAL_BUTTONS_CODE = """<div class="share"></div>""" + +In my experience this produces a broken, duplicate, semi-working thing. YMMV and if you make it work correctly, let me know how :-) + +The Easy Way +~~~~~~~~~~~~ + +Go to http://panzi.github.io/SocialSharePrivacy/ and use the provided form to get the code. Make sure you check "I already use JQuery" +if you are using one of the themes that require it, like site or default, select the services you want, and use your disqus name if +you have one. + +It will give you 3 code snippets: + +"Insert this once in the head of your page" + Put it in ``BODY_END`` + +"Insert this wherever you want a share widget displayed" + Put it in ``SOCIAL_BUTTONS_CODE`` + +"Insert this once anywhere after the other code" + Put it in ``BODY_END`` + +That should give you a working integration (not tested) diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile new file mode 100644 index 0000000..4e8e36e --- /dev/null +++ b/docs/sphinx/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Nikola.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Nikola.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/Nikola" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Nikola" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py new file mode 100644 index 0000000..9e24c8f --- /dev/null +++ b/docs/sphinx/conf.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +# +# Nikola documentation build configuration file, created by +# sphinx-quickstart on Sun Sep 22 17:43:37 2013. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +from __future__ import unicode_literals + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +try: + import sphinxcontrib.gist # NOQA + extensions = ['sphinxcontrib.gist'] +except ImportError: + extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.txt' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Nikola' +copyright = '2013, The Nikola Contributors' + +# The version info for the project yo're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '6.2.0' +# The full version, including alpha/beta/rc tags. +release = '6.2.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'Nikoladoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + #'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + #'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + #'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'Nikola.tex', 'Nikola Documentation', + 'The Nikola Contributors', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'nikola', 'Nikola Documentation', + ['The Nikola Contributors'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'Nikola', 'Nikola Documentation', + 'The Nikola Contributors', 'Nikola', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +primary_domain = None diff --git a/docs/sphinx/creating-a-site.txt b/docs/sphinx/creating-a-site.txt new file mode 120000 index 0000000..85f2ab2 --- /dev/null +++ b/docs/sphinx/creating-a-site.txt @@ -0,0 +1 @@ +../creating-a-site.txt
\ No newline at end of file diff --git a/docs/sphinx/creating-a-theme.txt b/docs/sphinx/creating-a-theme.txt new file mode 120000 index 0000000..6ddf35a --- /dev/null +++ b/docs/sphinx/creating-a-theme.txt @@ -0,0 +1 @@ +../creating-a-theme.txt
\ No newline at end of file diff --git a/docs/sphinx/extending.txt b/docs/sphinx/extending.txt new file mode 120000 index 0000000..1da5af1 --- /dev/null +++ b/docs/sphinx/extending.txt @@ -0,0 +1 @@ +../extending.txt
\ No newline at end of file diff --git a/docs/sphinx/index.txt b/docs/sphinx/index.txt new file mode 100644 index 0000000..6d899ab --- /dev/null +++ b/docs/sphinx/index.txt @@ -0,0 +1,27 @@ +Nikola Documentation +==================== + +Those are the docs for the current GitHub master. It might be incompatible +with the stable release. The docs for the stable release are available `on +the Nikola website <http://getnikola.com/documentation.html>`_. + +.. toctree:: + :maxdepth: 2 + + manual + upgrading-to-v6 + creating-a-site + creating-a-theme + theming + extending + internals + tests + social_buttons + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/sphinx/internals.txt b/docs/sphinx/internals.txt new file mode 120000 index 0000000..f0f3f05 --- /dev/null +++ b/docs/sphinx/internals.txt @@ -0,0 +1 @@ +../internals.txt
\ No newline at end of file diff --git a/docs/sphinx/make.bat b/docs/sphinx/make.bat new file mode 100644 index 0000000..8e3b6a1 --- /dev/null +++ b/docs/sphinx/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+ set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+ set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+ :help
+ echo.Please use `make ^<target^>` where ^<target^> is one of
+ echo. html to make standalone HTML files
+ echo. dirhtml to make HTML files named index.html in directories
+ echo. singlehtml to make a single large HTML file
+ echo. pickle to make pickle files
+ echo. json to make JSON files
+ echo. htmlhelp to make HTML files and a HTML help project
+ echo. qthelp to make HTML files and a qthelp project
+ echo. devhelp to make HTML files and a Devhelp project
+ echo. epub to make an epub
+ echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+ echo. text to make text files
+ echo. man to make manual pages
+ echo. texinfo to make Texinfo files
+ echo. gettext to make PO message catalogs
+ echo. changes to make an overview over all changed/added/deprecated items
+ echo. xml to make Docutils-native XML files
+ echo. pseudoxml to make pseudoxml-XML files for display purposes
+ echo. linkcheck to check all external links for integrity
+ echo. doctest to run all doctests embedded in the documentation if enabled
+ goto end
+)
+
+if "%1" == "clean" (
+ for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+ del /q /s %BUILDDIR%\*
+ goto end
+)
+
+
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+if "%1" == "html" (
+ %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+ goto end
+)
+
+if "%1" == "dirhtml" (
+ %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+ goto end
+)
+
+if "%1" == "singlehtml" (
+ %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+ goto end
+)
+
+if "%1" == "pickle" (
+ %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the pickle files.
+ goto end
+)
+
+if "%1" == "json" (
+ %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can process the JSON files.
+ goto end
+)
+
+if "%1" == "htmlhelp" (
+ %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+ goto end
+)
+
+if "%1" == "qthelp" (
+ %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+ echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Nikola.qhcp
+ echo.To view the help file:
+ echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Nikola.ghc
+ goto end
+)
+
+if "%1" == "devhelp" (
+ %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished.
+ goto end
+)
+
+if "%1" == "epub" (
+ %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The epub file is in %BUILDDIR%/epub.
+ goto end
+)
+
+if "%1" == "latex" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdf" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "latexpdfja" (
+ %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+ cd %BUILDDIR%/latex
+ make all-pdf-ja
+ cd %BUILDDIR%/..
+ echo.
+ echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+ goto end
+)
+
+if "%1" == "text" (
+ %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The text files are in %BUILDDIR%/text.
+ goto end
+)
+
+if "%1" == "man" (
+ %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The manual pages are in %BUILDDIR%/man.
+ goto end
+)
+
+if "%1" == "texinfo" (
+ %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+ goto end
+)
+
+if "%1" == "gettext" (
+ %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+ goto end
+)
+
+if "%1" == "changes" (
+ %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.The overview file is in %BUILDDIR%/changes.
+ goto end
+)
+
+if "%1" == "linkcheck" (
+ %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+ goto end
+)
+
+if "%1" == "doctest" (
+ %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+ goto end
+)
+
+if "%1" == "xml" (
+ %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The XML files are in %BUILDDIR%/xml.
+ goto end
+)
+
+if "%1" == "pseudoxml" (
+ %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+ if errorlevel 1 exit /b 1
+ echo.
+ echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+ goto end
+)
+
+:end
diff --git a/docs/sphinx/manual.txt b/docs/sphinx/manual.txt new file mode 120000 index 0000000..df591d6 --- /dev/null +++ b/docs/sphinx/manual.txt @@ -0,0 +1 @@ +../manual.txt
\ No newline at end of file diff --git a/docs/sphinx/social_buttons.txt b/docs/sphinx/social_buttons.txt new file mode 120000 index 0000000..12021c1 --- /dev/null +++ b/docs/sphinx/social_buttons.txt @@ -0,0 +1 @@ +../social_buttons.txt
\ No newline at end of file diff --git a/docs/sphinx/theming.txt b/docs/sphinx/theming.txt new file mode 120000 index 0000000..ed5f3b3 --- /dev/null +++ b/docs/sphinx/theming.txt @@ -0,0 +1 @@ +../theming.txt
\ No newline at end of file diff --git a/docs/sphinx/upgrading-to-v6.txt b/docs/sphinx/upgrading-to-v6.txt new file mode 120000 index 0000000..1c7e16f --- /dev/null +++ b/docs/sphinx/upgrading-to-v6.txt @@ -0,0 +1 @@ +../upgrading-to-v6.txt
\ No newline at end of file diff --git a/docs/theming.txt b/docs/theming.txt index d767cae..99492ab 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -1,7 +1,14 @@ +.. title: Theming Nikola +.. slug: theming +.. date: 2012/03/13 12:00 +.. tags: +.. link: +.. description: + Theming Nikola ============== -:Version: 5 +:Version: 6.2.1 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -14,10 +21,10 @@ This document is a reference about themes. If you want a tutorial, please read The Structure ------------- -Themes are located in the ``themes`` folder where Nikola is installed, one folder per theme. -The folder name is the theme name. +Themes are located in the ``themes`` folder where Nikola is installed, and in the ``themes`` folder +of your site, one folder per theme. The folder name is the theme name. -A Nikola theme consists of three folders: +A Nikola theme consists of the following folders (they are *all* optional): assets This is where you would put your CSS, Javascript and image files. It will be copied @@ -41,7 +48,13 @@ 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: +less + Files to be compiled into CSS using `LESS <http://lesscss.org/>`__ + +sass + Files to be compiled into CSS using `Sass <http://sass-lang.com/>`__ + +This mandatory file: parent A text file that, on its first line, contains the name of the **parent theme**. @@ -51,10 +64,19 @@ parent 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. + I recommend this: + + * If your theme uses bootstrap, inherit the ``bootstrap`` theme. + * If your theme uses bootstrap3, inherit the ``bootstrap3`` theme. + * If your theme uses Jinja as a template engine, inherit ``base-jinja`` + or ``bootstrap-jinja`` (available at http://themes.nikola.ralsina.com.ar) + * In any other case, inherit ``base``. + +And these optional files: + 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. @@ -89,108 +111,74 @@ so ``post.tmpl`` only define the content, and the layout is inherited from ``bas These are the templates that come with the included themes: -base.tmpl +``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) - * ``site_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. + but defines a few blocks that can be re-defined by inheriting templates. + + It has some separate pieces defined in ``base_helper.tmpl`` so they can be + easily overriden. For example, the Bootstrap theme adds a ``bootstrap_helper.tmpl`` + and then uses it to override things defined in base theme's ``base_helper.tmpl`` + +``index.tmpl`` + Template used to render the multipost indexes. The posts are in a ``posts`` variable. + Some functionality is in the ``index_helper.tmpl`` helper template. -gallery.tmpl - Template used for image galleries. Can use everything ``base.tmpl`` uses, plus: +``comments_helper.tmpl`` + This template handles comments. You should probably never touch it :-) + It uses a bunch of helper templates, one for each supported comment system: + ``disqus_helper.tmpl`` ``facebook_helper.tmpl`` ``googleplus_helper.tmpl`` + ``intensedebate_helper.tmpl`` ``livefyre_helper.tmpl`` ``moot_helper.tmpl`` + +``crumbs.tmpl`` ``slides.tmpl`` + These templates help render specific UI items, and can be tweaked as needed. + +``gallery.tmpl`` + Template used for image galleries. Interesting data includes: * ``text``: A descriptive text for the gallery. - * ``images``: A list of (thumbnail, image) paths. + * ``crumbs``: A list of ``link, crumb`` to implement a crumbbar. + * ``folders``: A list of folders to implement hierarchical gallery navigation. + * ``enable_comments``: To enable/disable comments in galleries. + * ``thumbnail_size``: The ``THUMBNAIL_SIZE`` option. + * ``photo_array``: a list of dictionaries, each containing: + + + ``url``: URL for the full-sized image. + + ``url_thumb``: URL for the thumbnail. + + ``title``: The title of the image. + + ``size``: A dict containing ``w`` and ``h``, the real size of the thumbnail. -index.tmpl - Template used to render the multipost indexes. Can use everything ``base.tmpl`` uses, plus: + * ``photo_array_json``: a JSON dump of photo_array, used in the bootstrap theme by flowr.js - * ``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, which it gets in ``items``, + a list of (text, link) elements. -list.tmpl - Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus: +``list_post.tmpl`` + Template used to display generic lists of posts, which it gets in ``posts``. - * ``items``: a list of (text, link) elements. +``post.tmpl`` + Template used by default for blog posts, gets the data in a ``post`` object + which is an instance of the Post class. Some functionality is in the + ``post_helper.tmpl`` template. +``story.tmpl`` + Used for pages that are not part of a blog, usually a cleaner, less + intrusive layout than ``post.tmpl``, but same parameters. -list_post.tmpl - Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus: +``listing.tmpl`` + Used to display code listings. - * ``posts``: a list of Post objects. +``tags.tmpl`` + Used to display the list of tags and categories. ``tag.tmpl`` is used to show the contents + of a single tag or category. +You can add other templates for specific pages, which the user can then use in his ``POSTS`` +or ``PAGES`` option in ``conf.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. -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. +Also, you can specify a custom template to be used by a post or page via the ``template`` metadata, +and custom templates can be added in the ``templates/`` folder of your site. Messages and Translations ------------------------- @@ -200,3 +188,29 @@ at https://www.transifex.com/projects/p/nikola/ If you want to create a theme that has new strings, and you want those strings to be translatable, then your theme will need a custom ``messages`` folder. + +`LESS <http://lesscss.org/>`__ and `Sass <http://sass-lang.com/>`__ +------------------------------------------------------------------- + +.. note:: + The LESS and Sass compilers will be moved to the Plugins Index in + Nikola v7.0.0. + +If you want to use those CSS extensions, you can — just store your files +in the ``less`` or ``sass`` directory of your theme. + +In order to have them work, you need to create a list of ``.less`` or +``.scss/.sass`` files to compile — the list should be in a file named +``targets`` in the respective directory (``less``/``sass``). + +The files listed in the ``targets`` file will be passed to the respective +compiler, which you have to install manually (``lessc`` which comes from +the Node.js package named ``less`` or ``sass`` from a Ruby package aptly +named ``sass``). Whatever the compiler outputs will be saved as a CSS +file in your rendered site, with the ``.css`` extension. + +.. note:: + Conflicts may occur if you have two files with the same base name + but a different extension. Pay attention to how you name your files + or your site won’t build! (Nikola will tell you what’s wrong when + this happens) diff --git a/docs/upgrading-to-v6.txt b/docs/upgrading-to-v6.txt new file mode 100644 index 0000000..386d6ab --- /dev/null +++ b/docs/upgrading-to-v6.txt @@ -0,0 +1,81 @@ +.. title: Upgrading to v6 +.. slug: upgrading-to-v6 +.. date: 2013/08/23 23:00 +.. tags: +.. link: +.. description: + +Upgrading to v6 +=============== + +:Version: 6.2.1 + +Nikola tries fairly hard to be compatible between versions. However, there were +a few areas which were getting clunky, and needed fxing. So, here's what you may +need to change in your site. + +If you need to change anything else, or something breaks, please write at nikola-discuss +and I'll add further tweaks here. + +Themes +------ + +**NOTE** + The install_theme command is not working yet, get themes from https://github.com/getnikola/nikola-themes + +**NOTE** + There is no equivalent for the jinja-default theme yet. If you have a custom, + jinja-based theme, upgrading is probably a bad idea right now. + + +Themes have been renamed: + +* site => bootstrap +* orphan => base + +Theme added: + +* base-jinja + +Themes have been moved out of nikola and into nikola-themes: + +* default => oldfashioned at nikola-themes +* jinja-default => not there yet, coming soon +* monospace => monospace at nikola-themes +* site-reveal => reveal at nikola-themes + +You may have to change your ``THEME`` setting, or change the ``parent`` if you are +using a custom theme. Also, some templates have been tweaked, but nothing should +break for you. + +Facebook comments support changed the HTML tag to: + +.. code-block: html + + <html% if comment_system == 'facebook': xmlns:fb="http://ogp.me/ns/fb#" + %endif lang="${lang}"> + + +Comments +~~~~~~~~ + +If you want a custom theme to support comment systems other than disqus, you will need to: + +1) Replace mentions of disqus_helper.tmpl with comments_helper.tmpl +2) Replace mentions of html_disqus with comment_form +3) Replace mentions of html_disqus_link with comment_link +4) Replace mentions of html_disqus_script with comment_link_script + +If you don't, your theme should work just fine, but support only disqus comments. + + +Configuration +------------- + +A number of options have been renamed. In all cases, the behaviour should be **exactly** as +before. If it's not, let me know. Also, you will get warnings. That doesn't mean things +broke. They are there to inform you of what's happening, and that you need to tweak +your config. + +All the deprecated options will work during the v6 cycle, and only be removed in v7, when +those warnings will become errors. |