77The Nikola Handbook
88===================
99
10- :Version: 7.5.1
10+ :Version: 7.6.0
1111
1212.. class:: alert alert-info pull-right
1313
@@ -19,7 +19,7 @@ All You Need to Know
1919
2020After you have Nikola `installed <#installing-nikola>`_:
2121
22- Create a empty site (with a setup wizard):
22+ Create an empty site (with a setup wizard):
2323 ``nikola init mysite``
2424
2525You can create a site with demo files in it with ``nikola init --demo mysite``
@@ -31,15 +31,14 @@ Create a post:
3131
3232Edit the post:
3333 The filename should be in the output of the previous command.
34+ You can also use ``nikola new_post -e`` to open an editor automatically.
3435
3536Build the site:
3637 ``nikola build``
3738
38- Start the test server:
39- ``nikola serve``
39+ Start the test server and open a browser (http://127.0.0.1:8000/) :
40+ ``nikola serve -b ``
4041
41- See the site:
42- http://127.0.0.1:8000
4342
4443That should get you going. If you want to know more, this manual will always be here
4544for you.
@@ -57,7 +56,7 @@ that it takes some texts you wrote, and uses them to create a folder full
5756of HTML files. If you upload that folder to a server, you will have a
5857rather full-featured website, done with little effort.
5958
60- It's original goal is to create blogs, but it supports most kind of sites, and
59+ Its original goal is to create blogs, but it supports most kind of sites, and
6160can be used as a CMS, as long as what you present to the user is your own content
6261instead of something the user generates.
6362
@@ -503,6 +502,9 @@ to your configuration::
503502 Like tags, except each post can have only one, and they usually have
504503 more descriptive names.
505504
505+ filters
506+ See the `Post Processing Filters`_ section.
507+
506508 hidetitle
507509 Set "True" if you do not want to see the **page** title as a
508510 heading of the output html file (does not work for posts).
@@ -821,6 +823,102 @@ setup.
821823 the same extension as is set in ``COMPILERS`` and configure the outputs
822824 properly.
823825
826+ Markdown
827+ ````````
828+
829+ To use Markdown in your posts/pages, make sure ``markdown`` is in your
830+ ``COMPILERS`` and that at least one of your desired extensions is defined in
831+ ``POSTS`` and ``PAGES``.
832+
833+ You can use Python-Markdown extensions by setting the ``MARKDOWN_EXTENSIONS``
834+ config option:
835+
836+ .. code:: python
837+
838+ MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra']
839+
840+ IPython Notebook/Jupyter
841+ ````````````````````````
842+
843+ To use Jupyter notebooks (previously known as IPython Notebooks) as posts/pages,
844+ make sure ``ipynb`` is in your ``COMPILERS`` and that the ``.ipynb`` extension
845+ is defined in ``POSTS`` and ``PAGES``.
846+
847+ The ``-f`` argument to ``new_post`` should be used in the ``ipynb@KERNEL`` format.
848+ It defaults to Python in the version used by Nikola if not specified.
849+
850+ HTML
851+ ````
852+
853+ To use plain HTML in your posts/pages, make sure ``html`` is in your
854+ ``COMPILERS``
855+ and that the ``.html`` extension is defined in ``POSTS`` and ``PAGES``.
856+
857+ PHP
858+ ```
859+
860+ There are two ways of using PHP within Nikola:
861+
862+ 1. To use PHP in your posts/pages (inside your site, with the theme and
863+ everything), make sure ``php`` is in your ``COMPILERS`` and that the ``.php``
864+ extension is defined in ``POSTS`` and ``PAGES``.
865+ 2. To use PHP as standalone files (without any modifications), put them in
866+ ``files/`` (or whatever ``FILES_FOLDERS`` is configured to).
867+
868+ Pandoc
869+ ``````
870+
871+ To use Pandoc, you must uncomment the entry in ``COMPILERS`` and set the
872+ extensions list to your desired extensions while also removing them from their
873+ original compilers. The input format is inferred from the extension by Pandoc.
874+
875+ Using Pandoc for reStructuredText, Markdown and other input formats that have a
876+ standalone Nikola plugin is **not recommended** as it disables plugins and
877+ extensions that are usually provided by Nikola.
878+
879+ Indexes
880+ ~~~~~~~
881+
882+ All your posts that are not drafts, private or dated in the future, will be
883+ shown in indexes.
884+
885+ Settings
886+ ````````
887+
888+ Indexes are put in the ``INDEX_PATH`` directory, which defaults to an empty
889+ string (site root). The “main” index is ``index.html``, and all the further
890+ indexes are ``index-*.html``, respectively.
891+
892+ By default, 10 posts are displayed on an index page. This can be changed with
893+ ``INDEX_DISPLAY_POST_COUNT``. Indexes can show full posts or just the teasers,
894+ as controlled by the ``INDEX_TEASERS`` setting (defaults to ``False``).
895+
896+ Titles of the pages can be controlled by using ``INDEXES_TITLES``,
897+ ``INDEXES_PAGES`` and ``INDEXES_PAGES_MAIN`` settings.
898+
899+ Categories and tags use simple lists by default that show only titles and
900+ dates; however, you can switch them to full indexes by using
901+ ``CATEGORY_PAGES_ARE_INDEXES`` and ``TAG_PAGES_ARE_INDEXES``, respectively.
902+
903+ Static indexes
904+ ``````````````
905+
906+ Nikola uses *static indexes* by default. This means that ``index-1.html`` has
907+ the oldest posts, and the newest posts past the first 10 are in
908+ ``index-N.html``, where ``N`` is the highest number. Only the page with the
909+ highest number and the main page (``index-N.html`` and ``index.html``) are
910+ rebuilt (the others remain unchanged). The page that appears when you click
911+ *Older posts* on the index page, ``index-N.html``, might contain **less than 10
912+ posts** if there are not enough posts to fill up all pages.
913+
914+ This can be disabled by setting ``INDEXES_STATIC`` to ``False``. In that mode,
915+ ``index-1.html`` contains all the newest posts past the first 10 and will
916+ always contain 10 posts (unless you have less than 20). The last page,
917+ ``index-N.html``, contains the oldest posts, and might contain less than 10
918+ posts. This is how many blog engines and CMSes behave. Note that this will
919+ lead to rebuilding all index pages, which might be a problem for larger blogs
920+ (with a lot of index pages).
921+
824922Creating a Page
825923---------------
826924
@@ -1364,6 +1462,21 @@ html_tidy_wrap_attr
13641462html_tidy_mini
13651463 Minify HTML 5 into smaller documents with `tidy5 <http://www.html-tidy.org/>`_
13661464
1465+ html_tidy_withconfig
1466+ Run `tidy5 <http://www.html-tidy.org/>`_ with ``tidy5.conf`` as the config file (supplied by user)
1467+
1468+ html5lib_minify
1469+ Minify HTML5 using html5lib_minify
1470+
1471+ html5lib_xmllike
1472+ Format using html5lib
1473+
1474+ typogrify
1475+ Improve typography using `typogrify <http://static.mintchaos.com/projects/typogrify/>`__
1476+
1477+ typogrify_sans_widont
1478+ Same as typogrify without the widont filter
1479+
13671480minify_lines
13681481 **THIS FILTER HAS BEEN TURNED INTO A NOOP** and currently does nothing.
13691482
@@ -1379,8 +1492,11 @@ optipng
13791492jpegoptim
13801493 Compress JPEG files using `jpegoptim <http://www.kokkonen.net/tjko/projects.html>`_
13811494
1382- typogrify
1383- Improve typography using `typogrify <https://github.com/mintchaos/typogrify>`_
1495+
1496+ You can apply filters to specific posts or pages by using the ``filters`` metadata field::
1497+
1498+ .. filters:: filters.html_tidy_nowrap, "sed s/foo/bar"
1499+
13841500
13851501
13861502Optimizing Your Website
0 commit comments