diff options
Diffstat (limited to 'docs/manual.txt')
| -rw-r--r-- | docs/manual.txt | 276 |
1 files changed, 168 insertions, 108 deletions
diff --git a/docs/manual.txt b/docs/manual.txt index caf9780..b2290c2 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -1,7 +1,7 @@ The Nikola Handbook =================== -:Version: 5.3 +:Version: 5.4.2 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -226,7 +226,7 @@ libxml/xmlversion.h: No such file or directory`` when running ``pip install -r r Debian systems: sudo apt-get install libxml2-dev - sudo apt-get install libxslt1-dev + sudo apt-get install libxslt1-dev RHEL systems: @@ -235,7 +235,7 @@ RHEL systems: Getting Started --------------- -To create posts and pages in Nikola, you write them in one of the supported input formats. +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 for textile and WikiCreole and even for just writing HTML. @@ -304,21 +304,32 @@ part of the site using task names, for example ``nikola build render_pages``, an Nikola also has other commands besides ``build``:: $ nikola help - Usage: nikola command [options] - + Nikola Available commands: - - nikola bootswatch_theme: Given a swatch name and a parent theme, creates a custom theme. - nikola build: Build the site. - nikola check: Check the generated site - nikola deploy: Deploy the site - nikola import_wordpress: Import a wordpress site from a XML dump (requires markdown). - 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 + 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 The ``serve`` command starts a web server so you can see the site you are creating:: @@ -340,25 +351,24 @@ Example usage:: Creating a Blog Post -------------------- -A post consists of two files, a metadata file (``post-title.meta``) and a -file containing the contents written in `restructured text <http://docutils.sf.net>`_ -(``post-title.txt``), markdown or HTML. Which input type is used is guessed using -the ``post_compilers`` option in ``conf.py`` but by default, the extensions -supported are: - -.txt .rst - Restructured Text +To create a new post, the easiest way is to run ``nikola new_post``. You will +be asked for a title for your post, and it will tell you where the post's file +is located. -.md .markdown .mdown - Markdown +By default, that file will contain also some extra information about your post ("the metadata"). +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. -.htm .html - HTML +The contents of your post have to be written (by default) in `restructured text <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. -The default configuration expects them to be placed in ``posts`` but that can be +You can control what markup compiler is used for each file extension with the ``post_compilers`` +option. The default configuration expects them to be placed in ``posts`` but that can be changed (see below, the post_pages option) -You can just create them in ``posts`` or use a little helper task provided by Nikola:: +This is how it works:: $ nikola new_post Creating New Post @@ -375,19 +385,19 @@ The content of that file is as follows:: .. tags: .. link: .. description: + Write your post here. -The first line is the title. The second one is the pagename. Since often titles will have +The ``slug`` is the pagename. Since often titles will have characters that look bad on URLs, it's generated as a "clean" version of the title. The third line is the post's date, and is set to "now". -You can add three more optional lines. A fourth line that is a list of tags -separated with commas (spaces around the commas are ignored):: +The other lines are optional. Tags are comma-separated. The ``link`` is an original +source for the content, and ``description`` is mostly useful for SEO. - programming, python, fame, fortune +You can add your own metadata fields in the same manner, if you use a theme that +supports them (for example: ``.. author: John Doe``) -A fifth line that's a URL for an original source of the post, and a sixth line -that's the page description. .. note:: The Two-File Format @@ -460,20 +470,21 @@ one in the list if all of them have it set to False. The ``new_post`` command supports some options:: - $ nikola new_post --help - Usage: nikola new_post [options] - + $ nikola help new_post + Purpose: Create a new blog post or site page. + Usage: nikola new_post [options] [path] + Options: - -h, --help show this help message and exit - -p, --page Create a page instead of a blog post. - -t TITLE, --title=TITLE - Title for the page/post. - --tags=TAGS Comma-separated tags for the page/post. - -1 Create post with embedded metadata (single file - format). - -f POST_FORMAT, --format=POST_FORMAT - Format for post (rest or markdown) + -p, --page Create a page instead of a blog post. + -t ARG, --title=ARG Title for the page/post. + --tags=ARG Comma-separated tags for the page/post. + -1 Create post with embedded metadata (single file format) + -2 Create post with separate metadata (two file format) + -f ARG, --format=ARG Markup format for post, one of rest, markdown, wiki, bbcode, html, textile, txt2tags +The optional ``path`` parameter tells nikola exactly where to put it instead of guessing from your config. +So, if you do ``nikola new_post posts/random/foo.txt`` you will have a post in that path, with +"foo" as its slug. Teasers ~~~~~~~ @@ -497,6 +508,11 @@ this behaviour with your ``conf.py``: ``INDEX_TEASERS`` defines whether index page should display the whole contents or only teasers. ``RSS_TEASERS`` works the same way for your RSS feeds. +By default, teasers will include a "read more" link at the end. If you want to +change that text, you can use a custom teaser:: + + .. TEASER_END: click to read the rest of the article + Drafts ~~~~~~ @@ -552,49 +568,14 @@ commented, but just in case, here is a full, `customized example configuration <sampleconfig.html>`_ (the one I use for `my site <http://lateral.netmanagers.com.ar>`_) -Adding Files ------------- - -Any files you want to be in ``output/`` but are not generated by Nikola (for example, -``favicon.ico``, just put it in ``files/``. Everything there is copied into -``output`` by the ``copy_files`` task. Remember that you can't have files that collide -with files Nikola generates (it will give an error). - -.. admonition:: Important - - Don't put any files manually in ``output/``. Ever. Really. Maybe someday Nikola - will just wipe ``output/`` and then you will be sorry. So, please don't do that. - -If you want to copy more than one folder of static files into ``output`` you can -change the FILES_FOLDERS option:: - - # One or more folders containing files to be copied as-is into the output. - # The format is a dictionary of "source" "relative destination". - # Default is: - # FILES_FOLDERS = {'files': '' } - # Which means copy 'files' into 'output' - -Post Processing Filters ------------------------ +You surely want to edit these options:: -You can apply post processing to the files in your site, in order to optimize them -or change them in arbitrary ways. For example, you may want to compress all CSS -and JS files using yui-compressor. + # Data about this site + BLOG_TITLE = "Demo Site" + BLOG_URL = "http://nikola.ralsina.com.ar" + BLOG_EMAIL = "joe@demo.site" + BLOG_DESCRIPTION = "This is a demo site for Nikola." -To do that, you can use the provided helper adding this in your ``config.py``:: - - from nikola import filters - - FILTERS = { - ".css": [filters.yui_compressor], - ".js": [filters.yui_compressor], - } - -Where ``filters.yui_compressor`` is a helper function provided by Nikola. You can -replace that with strings describing command lines, or arbitrary python functions. - -If there's any specific thing you expect to be generally useful as a filter, contact -me and I will add it to the filters library so that more people use it. Customizing Your Site --------------------- @@ -602,15 +583,6 @@ Customizing Your Site There are lots of things you can do to personalize your website, but let's see the easy ones! -Basics - You can assume this needs to be changed:: - - # Data about this site - BLOG_TITLE = "Demo Site" - BLOG_URL = "http://nikola.ralsina.com.ar" - BLOG_EMAIL = "joe@demo.site" - BLOG_DESCRIPTION = "This is a demo site for Nikola." - CSS tweaking The default configuration includes a file, ``themes/default/assets/css/custom.css`` which is empty. Put your CSS there, for minimal disruption of the provided CSS files. @@ -643,6 +615,29 @@ Analytics a Google analytics snippet or something similar, but you can really put anything there. + +Adding Files +------------ + +Any files you want to be in ``output/`` but are not generated by Nikola (for example, +``favicon.ico``, just put it in ``files/``. Everything there is copied into +``output`` by the ``copy_files`` task. Remember that you can't have files that collide +with files Nikola generates (it will give an error). + +.. admonition:: Important + + Don't put any files manually in ``output/``. Ever. Really. Maybe someday Nikola + will just wipe ``output/`` and then you will be sorry. So, please don't do that. + +If you want to copy more than one folder of static files into ``output`` you can +change the FILES_FOLDERS option:: + + # One or more folders containing files to be copied as-is into the output. + # The format is a dictionary of "source" "relative destination". + # Default is: + # FILES_FOLDERS = {'files': '' } + # Which means copy 'files' into 'output' + Getting More Themes ------------------- @@ -765,6 +760,28 @@ be stripped. For example ``03_an_amazing_sunrise.jpg`` will be render as *An ama Here is a `demo gallery </galleries/demo>`_ of historic, public domain Nikola Tesla pictures taken from `this site <http://kerryr.net/pioneers/gallery/tesla.htm>`_. +Post Processing Filters +----------------------- + +You can apply post processing to the files in your site, in order to optimize them +or change them in arbitrary ways. For example, you may want to compress all CSS +and JS files using yui-compressor. + +To do that, you can use the provided helper adding this in your ``config.py``:: + + from nikola import filters + + FILTERS = { + ".css": [filters.yui_compressor], + ".js": [filters.yui_compressor], + } + +Where ``filters.yui_compressor`` is a helper function provided by Nikola. You can +replace that with strings describing command lines, or arbitrary python functions. + +If there's any specific thing you expect to be generally useful as a filter, contact +me and I will add it to the filters library so that more people use it. + Optimizing Your Website ----------------------- @@ -783,6 +800,9 @@ different ones, or about other webservers, please share! AddType text/css .css +#. Optionally you can greate static compressed copies and save some CPU on your server + with the GZIP_FILES option in Nikola. + #. 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 @@ -809,7 +829,7 @@ Once you have that, all you need to do is:: .. youtube:: 8N_tupPBtWQ Vimeo -~~~~~~~ +~~~~~ 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** @@ -827,6 +847,18 @@ You can override this if you wish:: height=240 width=320 +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:: + + [soundcloud url="http://api.soundcloud.com/tracks/78131362" + +The ID is 78131362 and you can embed the audio with this:: + + .. soundcloud:: 78131362 code-block ~~~~~~~~~~ @@ -892,22 +924,22 @@ Slideshows To create an image slideshow, you can use the ``slides`` directive. For example:: - .. slides:: + .. slides:: :preload: :play: 350 - + /galleries/demo/tesla_conducts_lg.jpg /galleries/demo/tesla_lightning2_lg.jpg /galleries/demo/tesla4_lg.jpg /galleries/demo/tesla_lightning1_lg.jpg /galleries/demo/tesla_tower1_lg.jpg -This is based on `slidejs <http://slidesjs.com/>`_ and it supports +This is based on `slidejs <http://slidesjs.com/>`_ and it supports `the options described there <http://slidesjs.com/#options>`_ with one minor tweak to make them fit in docutils convention: If the option takes a boolean value, you just have to add it or not. For example, to enable preloading, just use the ``:preload:`` option. -If the option takes any other kind of argument, just use it after the option, like ``play`` in the +If the option takes any other kind of argument, just use it after the option, like ``play`` in the above example. Importing Your Wordpress Site Into Nikola @@ -930,14 +962,14 @@ the following: * Will give you a url_map so you know where each old post was This is also useful for Disqus thread migration! - + * Will try to convert the content of your posts. This is *not* error free, because wordpress uses some unholy mix of HTML and strange things. Currently we are treating it as markdown, which does a reasonabe job of it. - - You will find your old posts in ``new_site/posts/post-title.wp`` in case you need to fix + + You will find your old posts in ``new_site/posts/post-title.wp`` in case you need to fix any of them. - + This feature is a work in progress, and the only way to improve it is to have it used for as many sites as possible and make it work better each time, so I am happy to get requests about it. @@ -962,6 +994,34 @@ With this command Nikola will import into the folder ``import_location``. If the folder already exists Nikola will not overwrite an existing ``conf.py``. Instead a new file with a timestamp at the end of the filename will be created. +Using Twitter Cards +------------------- + +Twitter Cards enable you to show additional information in Tweets that link +to you content. +Nikola supports `Twitter Cards <https://dev.twitter.com/docs/cards>`_. +They are implemented to use *Open Graph* tags whenever possible. + +.. admonition:: Important + + To use Twitter Cards you need to opt-in on Twitter. + To do so please use the form that can be found at https://dev.twitter.com/form/participate-twitter-cards + +To enable and configure your use of Twitter Cards please modify the +corresponding lines in your ``conf.py``. +An example configuration that uses the Twitter nickname of the website +and the authors Twitter user ID is found below. + +.. code-block:: Python + + TWITTER_CARD = { + 'use_twitter_cards': True, # enable Twitter Cards / Open Graph + 'site': '@website', # twitter nick for the website + # 'site:id': 123456, # Same as site, but the website's Twitter user ID instead. + # 'creator': '@username', # Username for the content creator / author. + 'creator:id': 654321, # Same as creator, but the Twitter user's ID. + } + License ------- |