diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/extending.txt | 301 | ||||
| -rw-r--r-- | docs/man/nikola.1 | 60 | ||||
| -rw-r--r-- | docs/manual.txt | 233 | ||||
| -rw-r--r-- | docs/theming.txt | 2 |
4 files changed, 492 insertions, 104 deletions
diff --git a/docs/extending.txt b/docs/extending.txt new file mode 100644 index 0000000..4bbc2ea --- /dev/null +++ b/docs/extending.txt @@ -0,0 +1,301 @@ +Extending Nikola +================ + +:Version: 5 +:Author: Roberto Alsina <ralsina@netmanagers.com.ar> + +.. class:: alert alert-info pull-right + +.. 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. + +Plugins consist of a metadata file (with ``.plugin`` extension) and +a python module (a ``.py`` file) or package (a folder containing +a ``__init__.py`` file. + +To use a plugin in your site, you just have to put it in a ``plugins`` +folder in your site. + +Plugins come in various flavours, aimed at extending different aspects +of Nikola. + +Command Plugins +--------------- + +When you run ``nikola --help`` you will see something like this:: + + $ nikola --help + Usage: nikola command [options] + + 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 + +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: + +First, the ``command_serve.plugin`` file: + +.. code_block:: init + + [Core] + Name = serve + Module = command_serve + + [Documentation] + Author = Roberto Alsina + Version = 0.1 + Website = http://nikola.ralsina.com.ar + Description = Start test server. + +For your own plugin, just change the values in a sensible way. The +``Module`` will be used to find the matching python module, in this case +``command_serve.py``, from which this is the interesting bit: + +.. code_block:: python + + from nikola.plugin_categories import Command + + # You have to inherit Command for this to be a + # command plugin: + + 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): + """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 + else: + os.chdir(out_dir) + httpd = HTTPServer((options.address, options.port), + OurHTTPRequestHandler) + sa = httpd.socket.getsockname() + 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 serve --help + 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) + + $ nikola serve -p 9000 + Serving HTTP on 127.0.0.1 port 9000 ... + +So, what can you do with commands? Well, anything you want, really. I have implemented +a sort of planet using it. So, be creative, and if you do something interesting, +let me know ;-) + +TemplateSystem Plugins +---------------------- + +Nikola supports Mako and Jinja2. If you prefer some other templating +system, then you will have to write a TemplateSystem plugin. Here's how they work. +First, you have to create a .plugin file. Here's the one for the Mako plugin: + +.. code_block:: ini + + [Core] + Name = mako + Module = template_mako + + [Documentation] + Author = Roberto Alsina + Version = 0.1 + Website = http://nikola.ralsina.com.ar + Description = Support for Mako templates. + +You will have to replace "mako" with your template system's name, and other data +in the obvious ways. + +The "Module" option is the name of the module, which has to look something like this, +a stub for a hypothetical system called "Templater": + +.. code_block:: python + + from nikola.plugin_categories import TemplateSystem + + # You have to inherit TemplateSystem + + class TemplaterTemplates(TemplateSystem): + """Wrapper for Templater templates.""" + + # name has to match Name in the .plugin file + name = "templater" + + # You *must* implement this, even if to return [] + # It should return a list of all the files that, + # when changed, may affect the template's output. + # usually this involves template inheritance and + # inclusion. + def get_deps(self, filename): + return [] + + # A list of directories where the templates will be + # located. Most template systems have some sort of + # template loading tool that can use this. + + def set_directories(self, directories): + """Createa 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 + # uses for rendering. + + def render_template(self, template_name, output_name, + context, global_context): + """Render the template into output_name using context.""" + pass + + +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:: + + $ nikola build list + + build_bundles + copy_assets + copy_files + deploy + redirect + render_archive + render_galleries + render_indexes + render_listings + render_pages + render_posts + render_rss + render_site + render_sources + render_tags + sitemap + +These have access to the ``site`` object which contains your timeline and +your configuration. + +The critical bit of Task plugins is their ``gen_tasks`` method, which ``yields`` +`doit tasks <http://python-doit.sourceforge.net/tasks.html>`_ + +The details of how to handle dependencies, etc. are a bit too much for this +document, so I'll just leave you with an example, the ``copy_assets`` task. +First the ``task_copy_assets.plugin`` file, which you should copy and edit +in the logical ways: + +.. code_block:: ini + + [Core] + Name = copy_assets + Module = task_copy_assets + + [Documentation] + Author = Roberto Alsina + Version = 0.1 + Website = http://nikola.ralsina.com.ar + Description = Copy theme assets into output. + +And the ``task_copy_assets.py`` file, in its entirety: + +.. code_block:: python + + import os + + from nikola.plugin_categories import Task + from nikola import utils + + # Have to inherit Task to be a task plugin + class CopyAssets(Task): + """Copy theme assets into output.""" + + name = "copy_assets" + + # This yields the tasks + def gen_tasks(self): + """Create tasks to copy the assets of the whole theme chain. + + If a file is present on two themes, use the version + from the "youngest" theme. + """ + + # I put all the configurations and data the plugin uses + # in a dictionary because utils.config_changed will + # make it so that if these change, this task will be + # marked out of date, and run again. + + kw = { + "themes": self.site.THEMES, + "output_folder": self.site.config['OUTPUT_FOLDER'], + "filters": self.site.config['FILTERS'], + } + + tasks = {} + for theme_name in kw['themes']: + src = os.path.join(utils.get_theme_path(theme_name), 'assets') + dst = os.path.join(kw['output_folder'], 'assets') + for task in utils.copy_tree(src, dst): + if task['name'] in tasks: + continue + tasks[task['name']] = task + task['uptodate'] = task.get('uptodate', []) + \ + [utils.config_changed(kw)] + task['basename'] = self.name + # If your task generates files, please do this. + yield utils.apply_filters(task, kw['filters']) diff --git a/docs/man/nikola.1 b/docs/man/nikola.1 new file mode 100644 index 0000000..8f77039 --- /dev/null +++ b/docs/man/nikola.1 @@ -0,0 +1,60 @@ +====== +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/> diff --git a/docs/manual.txt b/docs/manual.txt index f8804e6..202afc1 100644 --- a/docs/manual.txt +++ b/docs/manual.txt @@ -1,7 +1,7 @@ The Nikola Handbook =================== -:Version: 2.1+svn +:Version: 5 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right @@ -18,16 +18,16 @@ Create a site: ``nikola init mysite`` Create a post: - ``doit new_post`` + ``nikola new_post`` Edit the post: The filename should be in the output of the previous command. Build the site: - ``doit`` + ``nikola build`` Start the test server: - ``doit serve`` + ``nikola serve`` See the site: http://127.0.0.1:8000 @@ -168,13 +168,14 @@ If you want to create a blog or a site, Nikola provides: * 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 Also: * A preview webserver * "Live" re-rendering while you edit -* "Smart" builds: only what changed gets rebuilt (usually in 1 or 2 seconds) -* Very easy to extend with minimal Python knowledge. +* "Smart" builds: only what changed gets rebuilt (usually in seconds) +* Easy to extend with minimal Python knowledge. Installing Nikola ----------------- @@ -187,24 +188,35 @@ The short version is: ``pip install https://github.com/ralsina/nikola/zipball/ma Longer version: -#. Get python, if you don't have it. -#. Get `doit <http://python-doit.sf.net>`_ -#. Get `docutils <http://docutils.sf.net>`_ -#. Get `Mako <http://makotemplates.org>`_ -#. Get `PIL <http://www.pythonware.com/products/pil/>`_ -#. Get `Pygments <http://pygments.org/>`_ -#. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ -#. Get `lxml <http://lxml.de/>`_ +#. Get `Nikola <http://nikola.ralsina.com.ar/>`_ +#. Install dependencies. To do that, either: -Any non-prehistorical version of the above should work, and if you are in Linux -you can try to use your distribution's packages if they exist, but the newer the better. + #. ``pip install -r requirements.txt`` or... + #. Install your distribution's packages for all the things + mentioned below, if they exist, or... + #. Get all of these manually: -Then get Nikola itself (<http://nikola.ralsina.com.ar/>), unzip it, and -run ``python setup.py install``. + #. Get python, if you don't have it. + #. Get `doit <http://python-doit.sf.net>`_ + #. Get `docutils <http://docutils.sf.net>`_ + #. Get `Mako <http://makotemplates.org>`_ + #. Get `PIL <http://www.pythonware.com/products/pil/>`_ + #. Get `Pygments <http://pygments.org/>`_ + #. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ + #. Get `lxml <http://lxml.de/>`_ + #. Get `yapsy <http://yapsy.sourceforge.com>`_ + #. Get `configparser <http://pypi.python.org/pypi/configparser/3.2.0r3>`_ + +#. run ``python setup.py install`` After that, run ``nikola init sitename`` and that will create a folder called ``sitename`` containing a functional demo site. +.. note:: Are you using Ubuntu? + + Then you can try using `my PPA <https://launchpad.net/~ralsina/+archive/nikola>`_ + and installing python-nikola + Getting Started --------------- @@ -216,10 +228,10 @@ First, let's see how you "build" your site. Nikola comes with a minimal site to The tool used to do builds is called `doit <http://python-doit.sf.net>`_, and it rebuilds the files that are not up to date, so your site always reflects your latest content. To do our -first build, just run "doit":: +first build, just run "nikola build":: - $ doit - Parsing metadata + $ nikola build + Scanning posts . . done! . render_posts:stories/manual.html . render_posts:posts/1.html . render_posts:stories/1.html @@ -238,66 +250,75 @@ first build, just run "doit":: Nikola will print a line for every output file it generates. If we do it again, that will be much much shorter:: - $ doit - Parsing metadata - . sitemap + $ nikola build + Scanning posts . . done! That is because `doit <http://python-doit.sf.net>`_ is smart enough not to generate all the pages again, unless you changed something that the page requires. So, if you change the text of a post, or its title, that post page, and all index pages where it is mentioned, will be recreated. If you change the post page template, then all the post pages will be rebuilt. -Nikola is a series of doit *tasks*, and you can see them by doing ``doit list``:: +Nikola is mostly a series of doit *tasks*, and you can see them by doing ``nikola build list``:: - $ doit list + $ nikola build list Scanning posts . . done! - copy_assets Create tasks to copy the assets of the whole theme chain. - copy_files Copy static files into the output folder. - deploy Deploy site. - new_page Create a new post (interactive). - new_post Create a new post (interactive). - redirect Generate redirections. - render_archive Render the post archives. - render_galleries Render image galleries. - render_indexes Render 10-post-per-page indexes. - render_pages Build final pages from metadata and HTML fragments. - render_posts Build HTML fragments from metadata and reSt. - render_rss Generate RSS feeds. - render_site Render the post archives. - render_sources Publish the rst sources because why not? - render_tags Render the tag pages. - serve Start test server. (Usage: doit serve [--address 127.0.0.1] [--port 8000]) - sitemap Generate Google sitemap. - -You can make Nikola redo everything by calling ``doit clean``, you can make it do just a specific -part of the site using task names, for example ``doit render_pages``, and even individual files like -``doit render_indexes:output/index.html`` - -The ``serve`` task is special, in that instead of generating a file it starts a web server so -you can see the site you are creating:: - - $ doit serve - Parsing metadata - . serve + build_bundles + copy_assets + copy_files + deploy + redirect + render_archive + render_galleries + render_indexes + render_listings + render_pages + render_posts + render_rss + render_site + render_sources + 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`` + +Nikola also has other commands besides ``build``:: + + $ nikola help + Usage: nikola command [options] + + 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 + +The ``serve`` command starts a web server so you can see the site you are creating:: + + $ nikola serve Serving HTTP on 127.0.0.1 port 8000 ... + After you do this, you can point your web browser to http://localhost:8000 and you should see -the sample site. This is useful as a "preview" of your work. You can combine add ``auto`` and do -``doit auto serve`` which makes doit automatically regenerate your pages as needed, and -it's a live preview! +the sample site. This is useful as a "preview" of your work. -By default, the ``serve`` task runs the web server on port 8000 on the IP address 127.0.0.1. +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`` (short version of ``--address``) or ``-p PORT_NUMBER`` (short version of ``--port``) Example usage:: - $ doit serve --address 0.0.0.0 --port 8080 - Parsing metadata - . serve + $ nikola serve --address 0.0.0.0 --port 8080 Serving HTTP on 0.0.0.0 port 8080 ... -The ``deploy`` task is discussed in the Deployment_ section. - Creating a Blog Post -------------------- @@ -321,21 +342,22 @@ changed (see below, the post_pages option) You can just create them in ``posts`` or use a little helper task provided by Nikola:: - $ doit new_post - Parsing metadata - . new_post + $ nikola new_post Creating New Post ----------------- - Enter title: How to Make Money - Your post's metadata is at: posts/how-to-make-money.meta + Enter title: How to make money Your post's text is at: posts/how-to-make-money.txt -The format for the ``.meta`` file is as follows:: +The content of that file is as follows:: - How to Make Money - how-to-make-money - 2012/04/09 13:59 + .. title: How to make money + .. slug: how-to-make-money + .. date: 2012/09/15 19:52:05 + .. tags: + .. link: + .. description: + Write your post here. The first line is the title. The second one is the pagename. Since often titles will have characters that look bad on URLs, it's generated as a "clean" version of the title. @@ -346,12 +368,22 @@ separated with commas (spaces around the commas are ignored):: programming, python, fame, fortune -And a fifth line that's a URL for an original source of the post. +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 + + Nikola originally used a separate ``.meta`` file. That will still work! + The format of the meta files is the same as shown above, but without the + explanations:: -And a sixth line that's the page description. + How to make money + how-to-make-money + 2012/09/15 19:52:05 If you are writing a multilingual site, you can also create a per-language -metadata file. This one can have two lines: +post file (for example: ``how-to-make-money.txt.es``). This one can have two +lines of metadata: 1) The translated title for the post or page 2) A translated version of the pagename @@ -404,22 +436,22 @@ configuration option:: It will use the first location that has the last parameter set to True, or the last one in the list if all of them have it set to False. -Alternatively, you can not have a meta file and embed the metadata in the post itself. +The ``new_post`` command supports some options:: -In restructured text:: + $ nikola new_post --help + Usage: nikola new_post [options] - .. tags: test,demo - .. slug: demo-test - .. date: 2012/04/09 13:59 - .. link: http://foo.bar/baz + 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) -In Markdown: - <!-- - .. tags: test,demo - .. slug: demo-test - .. date: 2012/04/09 13:59 - .. link: http://foo.bar/baz - --> Teasers ~~~~~~~ @@ -458,8 +490,8 @@ Pages are the same as posts, except that: The default configuration expects the page's metadata and text files to be on the ``stories`` folder, but that can be changed (see post_pages option above). -You can create the page's files manually or use the helper ``new_page`` that works exactly like -the ``new_post`` described above, except it will place the files in the folder that +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 has ``use_in_feed`` set to False. Redirections @@ -540,7 +572,8 @@ me and I will add it to the filters library so that more people use it. Customizing Your Site --------------------- -There are lots of things you can do to persoalize your website, but let's see the easy ones! +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:: @@ -588,19 +621,15 @@ Getting More Themes There are not so many themes for Nikola. On occasion, I port something I like, and make it available for download. Nikola has a builtin theme download/install mechanism, its -``install_theme`` task:: +``install_theme`` command:: - $ doit install_theme -l - Scanning posts . . done! - . install_theme + $ nikola install_theme -l Themes: ------- blogtxt readable - $ doit install_theme -n blogtxt - Scanning posts . . done! - . install_theme + $ nikola install_theme -n blogtxt Downloading: http://nikola.ralsina.com.ar/themes/blogtxt.zip Extracting: blogtxt into themes @@ -615,10 +644,8 @@ One other option is to tweak an existing theme using a different color scheme, typography and CSS in general. Nikola provides a ``bootswatch_theme`` option to create a custom theme by downloading free CSS files from http://bootswatch.com:: - $ doit bootswatch_theme -n custom_theme -s spruce -p site - Scanning posts . . done! - . bootswatch_theme - Creating custom_theme theme from spruce and site + $ 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. @@ -634,7 +661,7 @@ Deployment Nikola doesn't really have a concept of deployment. However, if you can specify your deployment procedure as a series of commands, you can put them in the ``DEPLOY_COMMANDS`` -option, and run them with ``doit deploy``. +option, and run them with ``nikola deploy``. One caveat is that if any command has a % in it, you should double them. diff --git a/docs/theming.txt b/docs/theming.txt index 339ecd4..93c7824 100644 --- a/docs/theming.txt +++ b/docs/theming.txt @@ -1,7 +1,7 @@ Theming Nikola ============== -:Version: 2.1+svn +:Version: 5 :Author: Roberto Alsina <ralsina@netmanagers.com.ar> .. class:: alert alert-info pull-right |