Setting up a Nikola site is really easy. You will need a few minutes’ time and a Python (2.7+/3.3+) interpreter.
-There are multiple ways to install Nikola. -
pip in a virtualenv. We recommend installing Nikola[extras] distribution to access some extra features, but you can drop the [extras] specifier if you don’t want them.There are multiple ways to install Nikola.
+pip in a virtualenv. We recommend installing the "Nikola[extras]" distribution to access some extra features, but you can drop the [extras] specifier if you don’t want them.Nikola is free open-source software, under the MIT license.
Nikola supports Windows! Keep in mind, though, that there are some - caveats:
-lxml and Pillow require compiled extensions. Compiling them on Windows is hard for most people. Fortunately, compiled packages exist. Check their PyPI pages to find official packages, the unofficial Gohlke wheels site, or get them somewhere else.\ as path separator (instead of /)\r\n) as the line separator (instead of LF \n)Nikola supports Windows! Keep in mind, though, that there are some caveats:
+pip install virtualenvlxml and Pillow require compiled extensions. Compiling them on Windows is hard for most people. Fortunately, compiled packages exist. Check their PyPI pages to find official packages, use the unofficial wheels by Christoph Gohlke, or get them somewhere else.
+ \ as path separator (instead of /)\r\n) as the line separator (instead of LF \n)Nikola is packaged for some Linux distributions, you may get that instead of installing via pip. Keep in mind that those packages might be outdated and that we don’t support versions that are too old. Proceed with care!
If you get errors about various files missing while compiling lxml, you must install headers for the libxml, libxslt and zlib libraries, like so:
Debian systems:
-# sudo apt-get install libxml2-dev libxslt1-dev zlib1g-devFedora 22+:
-# sudo dnf install libxslt-devel libxml2-devel zlib-develRed Hat/CentOS/Fedora 21:
-# sudo yum install libxslt-devel libxml2-devel zlib-develInstalling Nikola on OS X is easy. There are two ways to accomplish this:
+If you have Homebrew installed, skip the first step. If you have Python installed from Homebrew, skip the second step.
+brew install pythonpip install virtualenvYou can skip steps 3 and 4 if you use ~/Library/Python/2.7/bin/virtualenv as your virtualenv command.
easy_install --user --upgrade --always-copy pip virtualenvecho 'export PATH="~/Library/Python/2.7/bin:$PATH"' >> ~/.bash_profilesource ~/.bash_profileNikola is packaged for some Linux distributions, you may get that instead of installing via pip. Keep in mind that those packages might be outdated and that we don’t support versions that are too old. Proceed with care!
If you get an error to the effect of Python.h not found, you need to
- install development packages for Python.
Debian systems:
-# sudo apt-get install python-devFedora 22+:
-# sudo dnf install python-develRed Hat/CentOS/Fedora 21:
-# sudo yum install python-develNote that many other distros/operating systems (including Arch Linux, *BSD and OS X) do not require such packages, as C headers are included with the base distribution of Python.
-If you get errors about various files missing while compiling lxml, you must install headers for the libxml, libxslt and zlib libraries, like so:
Debian systems:
+
+# sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev
+
+ Fedora 22+:
+
+# sudo dnf install libxslt-devel libxml2-devel zlib-devel
+
+ Red Hat/CentOS/Fedora 21:
+
+# sudo yum install libxslt-devel libxml2-devel zlib-devel
+
If you get an error to the effect of Python.h not found, you need to install development packages for Python.
Debian systems:
+
+# sudo apt-get install python-dev
+
+ Fedora 22+:
+
+# sudo dnf install python-devel
+
+ Red Hat/CentOS/Fedora 21:
+
+# sudo yum install python-devel
+
+ Note that many other distros/operating systems (including Arch Linux, *BSD and OS X) do not require such packages, as C headers are included with the base distribution of Python.
You can also install Nikola from GitHub. This will get you the code that is still under development. It probably has bugs, but there are often new features or bugfixes.
-$ pip install "git+https://github.com/getnikola/nikola#egg=Nikola[extras]"You can also use tarballs downloaded from GitHub, or pip install -e with a local clone.
+You can also install Nikola from GitHub. This will get you the code that is still under development. It probably has bugs, but there are often new features or bugfixes.
+
+$ pip install "git+https://github.com/getnikola/nikola#egg=Nikola[extras]"
+
+ You can also use tarballs downloaded from GitHub, or pip install -e with a local clone.
$ virtualenv-3.4 nikola
+
+$ virtualenv nikola
Using base prefix '/usr'
New python executable in nikola/bin/python3
Also creating executable in nikola/bin/python
Installing setuptools, pip, wheel...done.
$ cd nikola
$ source bin/activate
-$ pip install "Nikola[extras]"
+$ pip install --upgrade "Nikola[extras]"
...snip...
Successfully installed Nikola
After installing Nikola, you should create a site. A site is a collection of all assets needed to create your site: configuration, posts, pages, images, and all other files and customizations.
-To create a site, you need to run nikola init --demo <directory_name>. A friendly wizard will be launched, letting you configure your site easily. The --demo option is used to fill your site with some demo content. (If you do not want the wizard, use the --quiet argument.)
To create a site, you need to run nikola init --demo <directory_name>. A friendly wizard will be launched, letting you configure your site easily. The --demo option is used to fill your site with some demo content. (If you do not want the wizard, use the --quiet argument.)
$ nikola init --demo my_first_site
+
+$ nikola init --demo my_first_site
Creating Nikola Site
====================
@@ -166,18 +192,17 @@ Step 2. Initialize a site
If you are looking for themes and addons, check out https://themes.getnikola.com/ and https://plugins.getnikola.com/.
Have fun!
INFO: init: A new site with example data has been created at my_first_site.
-INFO: init: See README.txt in that folder for more information.
-
+INFO: init: See README.txt in that folder for more information.You can now build the site you created. Just run nikola build. The output directory will then be filled with the contents of your site, which is now ready to deploy.
You can now build the site you created. Just run nikola build. The output directory will then be filled with the contents of your site, which is now ready to deploy.
$ cd my_first_site
+
+$ cd my_first_site
$ nikola build
Scanning posts....done!
. render_galleries:output/galleries
@@ -194,40 +219,38 @@ Step 3. Build your site
. render_pages:output/stories/a-study-in-scarlet/index.html
. sitemap:output/sitemap.xml
. sitemap:output/sitemapindex.xml
-. robots_file:output/robots.txt
-
+. robots_file:output/robots.txtYour site currently contains demo content — that is, some Nikola documentation, a demo gallery and listing, and a blog post welcoming you.
-You should make it more interesting and personal. Write your own post!
-To do that, you can just use nikola new_post -e. (The -e option will open the post in your text editor of choice; many more options are available)
You should make it more interesting and personal. Write your own post!
+To do that, you can just use nikola new_post -e. (The -e option will open the post in your text editor of choice; many more options are available)
The command will create the file for you in the right place, with the metadata headers and a writing prompt.
-By default, Nikola creates posts in reStructuredText. You can read the reStructuredText Primer to get accustomed to the syntax. You can also use many other input formats; to do this, your site needs some special configuration.
+By default, Nikola creates posts in reStructuredText. You can read the reStructuredText Primer to get accustomed to the syntax. You can also use many other input formats; to do this, your site needs some special configuration.
$ nikola new_post -e
+
+$ nikola new_post -e
Creating New Post
-----------------
Title: My First Blog Post!
Scanning posts....done!
-INFO: new_post: Your post's text is at: posts/my-first-blog-post.rst
-
+INFO: new_post: Your post's text is at: posts/my-first-blog-post.rstWhen you’re done writing your post, you must rebuild your site to make it visible on your site. Run nikola build again.
Note that the list of files is much shorter now: Nikola does fast, incremental rebuilds (courtesy of doit). Nikola built only the pages for this post, the indexes, the feeds, and the previous post (to add a Next post navigation button). All the demo pages and assets were left untouched, saving you time and resources (it does not have to work on building some larger things, and rsync will not have to upload everything)
When you’re done writing your post, you must rebuild your site to make it visible on your site. Run nikola build again.
Note that the list of files is much shorter now: Nikola does fast, incremental rebuilds (courtesy of doit). Nikola built only the pages for this post, the indexes, the feeds, and the previous post (to add a Next post navigation button). All the demo pages and assets were left untouched, saving you time and resources (it does not have to work on building some larger things, and rsync will not have to upload everything)
$ nikola build
+
+$ nikola build
Scanning posts....done!
. render_posts:timeline_changes
. render_posts:cache/posts/my-first-blog-post.html
@@ -239,38 +262,39 @@ Step 5. Rebuild your site
. generate_rss:output/rss.xml
. render_pages:output/posts/my-first-blog-post/index.html
. sitemap:output/sitemap.xml
-. sitemap:output/sitemapindex.xml
-
+. sitemap:output/sitemapindex.xmlYou’re done! You just created a Nikola site, wrote your first post and built your site. Congratulations!
-Run nikola serve --browser to start the development server and open your site in a web browser. Press Ctrl+C to stop the server.
Run nikola serve --browser to start the development server and open your site in a web browser. Press Ctrl+C to stop the server.
You can also use a server with automatic rebuilds. Note that both servers should be used for development only; use other deployment solutions instead.
$ nikola serve --browser
+
+$ nikola serve --browser
INFO: serve: Serving HTTP on 0.0.0.0 port 8000...
-INFO: serve: Opening http://0.0.0.0:8000/ in the default web browser...
-
+INFO: serve: Opening http://0.0.0.0:8000/ in the default web browser...-
nikola help.conf.py file to your liking.nikola help.conf.py file to your liking.Input formats other than reStructuredText need some configuration, which has been described in The Nikola Manual.
+Input formats other than reStructuredText need some configuration, which has been described in The Nikola Manual.
When you’re done exploring, you should remove the demo content before deploying it to your server. Remove the demo stories, welcome post, demo gallery and listing manually. Run nikola build to make them disappear from the archives. Note that this is not enough; you need to delete the now orphaned files. Nikola can do it for you — run nikola check --clean-files.
When you’re done exploring, you should remove the demo content before deploying it to your server. Remove the demo stories, welcome post, demo gallery and listing manually. Run nikola build to make them disappear from the archives. Note that this is not enough; you need to delete the now orphaned files. Nikola can do it for you — run nikola check --clean-files. Note that this command will delete all files in the output directory it does not know about, which can be dangerous — please back up your files or find out what will be deleted by using nikola orphans.
Hint: files in the files/ directory are copied to the output directory as-is.
The development server (nikola serve) should not be used outside of your local network. Instead, you should use a more serious web server. Nikola sites work on any web server which can host html files. You can use shared hosting, your own server (VPS/dedicated), GitHub Pages, or any other service that lets you host a website. For more details on deployment and related configuration, see the Deployment section in the Handbook.