diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/creating-a-site.txt | 181 | ||||
| -rw-r--r-- | docs/manual.txt | 276 | ||||
| -rw-r--r-- | docs/theming.txt | 4 |
3 files changed, 351 insertions, 110 deletions
diff --git a/docs/creating-a-site.txt b/docs/creating-a-site.txt new file mode 100644 index 0000000..41985c9 --- /dev/null +++ b/docs/creating-a-site.txt @@ -0,0 +1,181 @@ +.. slug: creating-a-site-not-a-blog-with-nikola +.. date: 2013/03/01 12:49:41 +.. tags: nikola, python +.. link: +.. description: + +Creating a Site (Not a Blog) with Nikola +======================================== + +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 +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 +empty semi-configured site:: + + $ nikola init mysite + Created empty site at mysite. + +Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py`` +configuration file: + +.. code-block:: python + + + ############################################## + # Configuration, please edit + ############################################## + + + # Data about this site + BLOG_AUTHOR = "Roberto Alsina" + BLOG_TITLE = "Not a Blog" + # This is the main URL for your site. It will be used + # in a prominent link + SITE_URL = "http://notablog.ralsina.com.ar" + BLOG_EMAIL = "ralsina@kde.org" + BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola." + + # + # Some things in the middle you don't really need to change... + # + + post_pages = ( + ("pages/*.txt", "", "story.tmpl", False), + ) + +And now we are ready to create our first page:: + + $ nikola new_post -p + Creating New Post + ----------------- + + Enter title: index + Your post's text is at: pages/index.txt + +.. note:: The ``-p`` option in the ``nikola new_post`` command means we are creating a page and not a blog post. + +We can now build and preview our site:: + + $ nikola build + Scanning posts.done! + . render_site:output/categories/index.html + . render_sources:output/index.txt + . render_rss:output/rss.xml + : + : + : [Much more of the same] + + $ nikola serve + Serving HTTP on 127.0.0.1 port 8000 ... + +And you can see your (very empty) site in http://localhost:8000 + +So, what's in that ``pages/index.txt`` file? + +.. code-block:: rest + + .. title: index + .. slug: index + .. date: 2013/03/01 10:26:17 + .. tags: + .. link: + .. description: + + + Write your post here. + +Title is the page title, slug is the name of the generated HTML file +(in this case it would be ``index.html``) the date doesn't matter much in +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 +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/>`_ +you can use anything you like from it: + +.. code-block:: rest + + .. title: Welcome To The Fake Site + .. slug: index + .. date: 2013/03/01 10:26:17 + .. tags: + .. link: + .. description: Fake Site version 1, welcome page! + + + .. class:: hero-unit span6 + + .. admonition:: This is a Fake Site + + It pretends to be about things, but is really just an example. + So, don't click this button, it leads nowhere. + + .. class:: btn + + Click Me! + + + .. class:: span5 + + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis. + Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque + gravida quam a mi dignissim consequat. Morbi sed iaculis mi. Vivamus ultrices + mattis euismod. Mauris aliquet magna eget mauris volutpat a egestas leo rhoncus. + In hac habitasse platea dictumst. Ut sed mi arcu. Nullam id massa eu orci + convallis accumsan. Nunc faucibus sodales justo ac ornare. In eu congue eros. + Pellentesque iaculis risus urna. Proin est lorem, scelerisque non elementum at, + semper vel velit. Phasellus consectetur orci vel tortor tempus imperdiet. Class + aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos + himenaeos. + + [And more in the same vein] + +.. 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" + +And that's it. You will want to change the SIDEBAR_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``: + + .. code-block:: python + + INDEX_PATH = "blog" + + 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). + +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 + +I hope this was helpful! 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 ------- diff --git a/docs/theming.txt b/docs/theming.txt index 33884e9..6c0c0e4 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -76,8 +76,8 @@ Templates --------- In templates there is a number of files whose name ends in ``.tmpl``. Those are the -theme's page templates. They are done usig the `Mako <http://makotemplates.org>`_ -or `Jinja2 <jinja.pocoo.org>`_ template languages. If you want to do a theme, you +theme's page templates. They are done using the `Mako <http://makotemplates.org>`_ +or `Jinja2 <http://jinja.pocoo.org>`_ template languages. If you want to do a theme, you should learn one first. What engine is used by the theme is declared in the ``engine`` file. The rest of this document explains Mako templates, but Jinja2 is fairly similar. |