-
Notifications
You must be signed in to change notification settings - Fork 446
/
manual.txt
2152 lines (1520 loc) · 77.9 KB
/
manual.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.. title: The Nikola Handbook
.. slug: handbook
.. date: 2012-03-30 23:00:00 UTC-03:00
.. link:
.. description:
.. tags: mathjax
.. author: The Nikola Team
The Nikola Handbook
===================
:Version: 7.7.4
.. class:: alert alert-info pull-right
.. contents::
All You Need to Know
--------------------
After you have Nikola `installed <https://getnikola.com/getting-started.html>`_:
Create an empty site (with a setup wizard):
``nikola init mysite``
You can create a site with demo files in it with ``nikola init --demo mysite``
The rest of these commands have to be executed inside the new ``mysite`` folder.
Create a post:
``nikola new_post``
Edit the post:
The filename should be in the output of the previous command.
You can also use ``nikola new_post -e`` to open an editor automatically.
Build the site:
``nikola build``
Start the test server and open a browser:
``nikola serve -b``
That should get you going. If you want to know more, this manual will always be here
for you.
DON'T READ THIS MANUAL. IF YOU NEED TO READ IT I FAILED, JUST USE THE THING.
On the other hand, if anything about Nikola is not as obvious as it should be, by all
means tell me about it :-)
What's Nikola and what can you do with it?
------------------------------------------
Nikola is a static website and blog generator. The very short explanation is
that it takes some texts you wrote, and uses them to create a folder full
of HTML files. If you upload that folder to a server, you will have a
rather full-featured website, done with little effort.
Its original goal is to create blogs, but it supports most kind of sites, and
can be used as a CMS, as long as what you present to the user is your own content
instead of something the user generates.
Nikola can do:
* A blog (`example <http://ralsina.me>`__)
* Your company's site
* Your personal site
* A software project's site (`example <https://getnikola.com>`__)
* A book's site
Since Nikola-based sites don't run any code on the server, there is no way to process
user input in forms.
Nikola can't do:
* Twitter
* Facebook
* An Issue tracker
* Anything with forms, really (except for `comments <#comments-and-annotations>`_!)
Keep in mind that "static" doesn't mean **boring**. You can have animations, slides
or whatever fancy CSS/HTML5 thingie you like. It only means all that HTML is
generated already before being uploaded. On the other hand, Nikola sites will
tend to be content-heavy. What Nikola is good at is at putting what you write
out there.
Getting Help
------------
.. class:: lead
`Get help here! <https://getnikola.com/contact.html>`_
TL;DR:
* You can file bugs at `the issue tracker <https://github.com/getnikola/nikola/issues>`__
* You can discuss Nikola at the `nikola-discuss google group <http://groups.google.com/group/nikola-discuss>`_
* You can subscribe to `the Nikola Blog <https://getnikola.com/blog>`_
* You can follow `Nikola on Twitter <https://twitter.com/GetNikola>`_
Why Static?
-----------
Most "modern" websites are *dynamic* in the sense that the contents of the site
live in a database, and are converted into presentation-ready HTML only when a
user wants to see the page. That's great. However, it presents some minor issues
that static site generators try to solve.
In a static site, the whole site, every page, *everything*, is created before
the first user even sees it and uploaded to the server as a simple folder full
of HTML files (and images, CSS, etc).
So, let's see some reasons for using static sites:
Security
Dynamic sites are prone to experience security issues. The solution for that
is constant vigilance, keeping the software behind the site updated, and
plain old good luck. The stack of software used to provide a static site,
like those Nikola generates, is much smaller (Just a web server).
A smaller software stack implies less security risk.
Obsolescence
If you create a site using (for example) WordPress, what happens when WordPress
releases a new version? You have to update your WordPress. That is not optional,
because of security and support issues. If I release a new version of Nikola, and
you don't update, *nothing* happens. You can continue to use the version you
have now forever, no problems.
Also, in the longer term, the very foundations of dynamic sites shift. Can you
still deploy a blog software based on Django 0.96? What happens when your
host stops supporting the php version you rely on? And so on.
You may say those are long term issues, or that they won't matter for years. Well,
I believe things should work forever, or as close to it as we can make them.
Nikola's static output and its input files will work as long as you can install
a Python 2.7/3.3 or newer under Linux, Windows, or OS X and can find a server
that sends files over HTTP. That's probably 10 or 15 years at least.
Also, static sites are easily handled by the Internet Archive.
Cost and Performance
On dynamic sites, every time a reader wants a page, a whole lot of database
queries are made. Then a whole pile of code chews that data, and HTML is
produced, which is sent to the user. All that requires CPU and memory.
On a static site, the highly optimized HTTP server reads the file from disk
(or, if it's a popular file, from disk cache), and sends it to the user. You could
probably serve a bazillion (technical term) pageviews from a phone using
static sites.
Lock-in
On server-side blog platforms, sometimes you can't export your own data, or
it's in strange formats you can't use in other services. I have switched
blogging platforms from Advogato to PyCs to two homebrew systems, to Nikola,
and have never lost a file, a URL, or a comment. That's because I have *always*
had my own data in a format of my choice.
With Nikola, you own your files, and you can do anything with them.
Components
----------
Nikola provides the following features:
* Blog support, including:
* Indexes
* RSS and Atom feeds
* Tags and categories, with pages and feeds
* Author pages and feeds (not generated if ``ENABLE_AUTHOR_PAGES`` is set to ``False`` or there is only one author)
* Archives with custom granularity (yearly or monthly)
* `Comments`_
* Client-side tag clouds (needs manual configuration)
* Static pages (not part of the blog)
* `Math`_ rendering (via MathJax)
* Custom output paths for generated pages
* Pretty URLs (without ``.html``) that don’t need web server support
* Easy page template customization
* Internationalization support (my own blog is English and Spanish)
* Sitemap generation (for search engines)
* Custom deployment (if it’s a command, you can use it)
* GitHub Pages deployment
* Themes, easy appearance customization
* `Multiple input formats <#supported-input-formats>`_, including reStructuredText and Markdown
* Easy-to-create image galleries
* Image thumbnail generation
* Support for displaying source code listings
* Image slideshows
* Custom search
* Asset (CSS/JS) bundling
* gzip compression (for sending via your web server)
* Open Graph, Twitter Cards
* Hyphenation
* Custom `post processing filters`_ (eg. for minifying files or better typography)
Getting Started
---------------
.. class:: lead
To set Nikola up and create your first site, read the `Getting Started Guide <https://getnikola.com/getting-started.html>`_.
Creating a Blog Post
--------------------
.. sidebar:: Magic Links
You will want to do things like "link from one post to another" or "link to an image gallery",
etc. Sure, you can just figure out the URLs for each thing and use that. Or you can use
Nikola's special link URLs. Those are done using the syntax ``link://kind/name`` and
a full list of the included ones is `here <link://slug/path-handlers>`__ (BTW, I linked
to that using ``link://slug/path-handlers``)
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.
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.
The contents of your post have to be written (by default) in `reStructuredText <http://docutils.sf.net>`__
but you can use a lot of different markups using the ``-f`` option.
Currently, Nikola supports reStructuredText, Markdown, IPython (Jupyter) Notebooks, HTML as input,
can also use Pandoc for conversion, and has support for BBCode, CreoleWiki, txt2tags, Textile
and more via plugins — for more details, read the `input format documentation
<#multiple-input-formats>`__.
You can learn reStructuredText syntax with the `reST quickstart <https://getnikola.com/quickstart.html>`__.
Please note that Nikola does not guarantee support for encodings other than
UTF-8. We recommend converting your input files to that encoding. It will
prevent bugs, and Nikola will write UTF-8 output anyway.
You can control what markup compiler is used for each file extension with the ``COMPILERS``
option. The default configuration expects them to be placed in ``posts`` but that can be
changed (see below, the ``POSTS`` and ``PAGES`` options)
This is how it works:
.. code:: console
$ nikola new_post
Creating New Post
-----------------
Title: How to make money
Scanning posts....done!
INFO: new_post: Your post's text is at: posts/how-to-make-money.rst
The content of that file is as follows:
.. code:: restructuredtext
.. title: How to make money
.. slug: how-to-make-money
.. date: 2012-09-15 19:52:05 UTC
.. tags:
.. link:
.. description:
.. type: text
Write your post here.
The ``slug`` is the page name. 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".
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.
``type`` is the post type, whatever you set here (prepended with ``post-``)
will become a CSS class of the ``<article>`` element for this post. Defaults to
``text`` (resulting in a ``post-text`` class)
You can add your own metadata fields in the same manner, if you use a theme that
supports them (for example: ``.. author: John Doe``)
To add these metadata fields to all new posts by default, you can set the
variable ``ADDITIONAL_METADATA`` in your configuration. For example, you can
add the author metadata to all new posts by default, by adding the following
to your configuration:
.. code:: python
ADDITIONAL_METADATA = {
'author': 'John Doe'
}
.. sidebar:: Other Metadata Fields
Nikola will also use other metadata fields:
author
Author of the post, will be used in the RSS feed and possibly in the post
display (theme-dependent)
annotations / noannotations
Override the value of the ``ANNOTATIONS`` option for this specific post or page.
category
Like tags, except each post can have only one, and they usually have
more descriptive names.
filters
See the `Post Processing Filters`_ section.
hidetitle
Set "True" if you do not want to see the **page** title as a
heading of the output html file (does not work for posts).
hyphenate
Set "True" if you want this document to be hyphenated even if you have
hyphenation disabled by default.
nocomments
Set to "True" to disable comments. Example:
.. code:: restructuredtext
.. nocomments: True
password
The post will be encrypted and invisible until the reader enters the password.
Also, the post's sourcecode will not be available.
WARNING: **DO NOT** use for real confidential data. The algorithm used (RC4) is insecure. The implementation may also be easily brute-forced. Please consider using something else if you need *real* encryption!
More information: `Issue #1547 <https://github.com/getnikola/nikola/issues/1547>`_
previewimage
Designate a preview or other representative image path relative to BASE_URL
for use with Open Graph for posts. Adds the image when sharing on social
media and many other uses.
.. code:: restructuredtext
.. previewimage: images/looks_great_on_facebook.png
The image can be of any size and dimension (services will crop and adapt)
but should less than 1 MB and be larger than 300x300 (ideally 600x600).
template
Change the template used to render this page/post specific page. That
template needs to either be part of the theme, or be placed in a
``templates/`` folder inside your site.
.. code:: restructuredtext
.. template: story.tmpl
enclosure
Add an enclosure to this post when it's used in RSS. See `more information about enclosures <http://en.wikipedia.org/wiki/RSS_enclosure>`__
.. 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 (i.e. only
the 7 base fields, in the order listed above), but without the
explanations:
.. code:: text
How to make money
how-to-make-money
2012-09-15 19:52:05 UTC
However, starting with Nikola v7, you can now use ``.meta`` files and put
all metadata you want, complete with the explanations — they look just like
the beginning of our reST files.
.. code:: restructuredtext
.. title: How to make money
.. slug: how-to-make-money
.. date: 2012-09-15 19:52:05 UTC
Both file formats are supported; however, the new format is preferred, if
possible.
If you are writing a multilingual site, you can also create a per-language
post file (for example: ``how-to-make-money.es.txt`` with the default TRANSLATIONS_PATTERN, see below).
This one can replace metadata of the default language, for example:
* The translated title for the post or page
* A translated version of the page name
The pattern used for finding translations is controlled by the
TRANSLATIONS_PATTERN variable in your configuration file.
The default is to put the language code before the file extension,
so the German translation of ``some_file.rst`` should be named
``some_file.de.rst``. This is because the TRANSLATIONS_PATTERN variable is by
default set to:
.. code:: python
TRANSLATIONS_PATTERN = "{path}.{lang}.{ext}"
.. note:: Considered languages
Nikola will only look for translation of input files for languages
specified in the TRANSLATIONS variable.
You can edit these files with your favourite text editor, and once you are happy
with the contents, generate the pages using ``nikola build``.
Nikola supports multiple languages for a post (we have almost 40 translations!). If you wish to
add support for more languages, check out `the Transifex page for Nikola <https://www.transifex.com/projects/p/nikola/>`_
The post page is generated using the ``post.tmpl`` template, which you can use
to customize the output.
The place where the post will be placed by ``new_post`` is based on the ``POSTS``
and ``PAGES`` configuration options:
.. code:: python
# POSTS and PAGES contains (wildcard, destination, template) tuples.
#
# The wildcard is used to generate a list of reSt source files
# (whatever/thing.txt).
#
# That fragment could have an associated metadata file (whatever/thing.meta),
# and optionally translated files (example for Spanish, with code "es"):
# whatever/thing.es.txt and whatever/thing.es.meta
#
# This assumes you use the default TRANSLATIONS_PATTERN.
#
# From those files, a set of HTML fragment files will be generated:
# cache/whatever/thing.html (and maybe cache/whatever/thing.html.es)
#
# These files are combined with the template to produce rendered
# pages, which will be placed at
# output / TRANSLATIONS[lang] / destination / pagename.html
#
# where "pagename" is the "slug" specified in the metadata file.
#
# The difference between POSTS and PAGES is that POSTS are added
# to feeds and are considered part of a blog, while PAGES are
# just independent HTML pages.
#
POSTS = (
("posts/*.txt", "posts", "post.tmpl"),
("posts/*.rst", "posts", "post.tmpl"),
)
PAGES = (
("stories/*.txt", "stories", "story.tmpl"),
("stories/*.rst", "stories", "story.tmpl"),
)
.. note:: POSTS and PAGES are not flat!
Even if the syntax may suggest you can't, you can create any directory structure you want
inside ``posts/`` or ``stories/`` and it will be reflected in the output. For example,
``posts/foo/bar.txt`` would produce ``output/posts/foo/bar.html``, assuming the slug is also ``bar``.
If you have ``PRETTY_URLS`` enabled, that would be ``output/posts/foo/bar/index.html``.
``new_post`` will use the *first* path in ``POSTS`` (or ``PAGES`` if ``-p`` is
supplied) that ends with the extension of your desired markup format (as
defined in ``COMPILERS`` in ``conf.py``) as the directory that the new post will be
written into. If no such entry can be found, the post won’t be created.
The ``new_post`` command supports some options:
.. code:: text
$ nikola help new_post
Purpose: create a new blog post or site page
Usage: nikola new_post [options] [path]
Options:
-p, --page Create a page instead of a blog post. (see also: `nikola new_page`)
-t ARG, --title=ARG Title for the post.
-a ARG, --author=ARG Author of the post.
--tags=ARG Comma-separated tags for the post.
-1 Create the post with embedded metadata (single file format)
-2 Create the post with separate metadata (two file format)
-e Open the post (and meta file, if any) in $EDITOR after creation.
-f ARG, --format=ARG Markup format for the post (use --available-formats for list)
-F, --available-formats List all available input formats
-s Schedule the post based on recurrence rule
-i ARG, --import=ARG Import an existing file instead of creating a placeholder
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
~~~~~~~
You may not want to show the complete content of your posts either on your
index page or in RSS feeds, but to display instead only the beginning of them.
If it's the case, you only need to add a "magical comment" in your post.
In reStructuredText:
.. code:: restructuredtext
.. TEASER_END
In Markdown (or basically, the resulting HTML of any format):
.. code:: html
<!-- TEASER_END -->
By default all your RSS feeds will be shortened (they'll contain only teasers)
whereas your index page will still show complete posts. You can change
this behaviour with your ``conf.py``: ``INDEX_TEASERS`` defines whether index
page should display the whole contents or only teasers. ``FEED_TEASERS``
works the same way for your Atom and 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:
.. code:: restructuredtext
.. TEASER_END: click to read the rest of the article
You can override the default value for ``TEASER_END`` in ``conf.py`` — for
example, the following example will work for ``.. more``, and will be
compatible with both WordPress and Nikola posts:
.. code:: python
import re
TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END)(:(.+))?\s*-->', re.IGNORECASE)
Or you can completely customize the link using the ``READ_MORE_LINK`` option.
.. code:: python
# A HTML fragment with the Read more... link.
# The following tags exist and are replaced for you:
# {link} A link to the full post page.
# {read_more} The string “Read more” in the current language.
# {{ A literal { (U+007B LEFT CURLY BRACKET)
# }} A literal } (U+007D RIGHT CURLY BRACKET)
# READ_MORE_LINK = '<p class="more"><a href="{link}">{read_more}…</a></p>'
Drafts
~~~~~~
If you add a "draft" tag to a post, then it will not be shown in indexes and feeds.
It *will* be compiled, and if you deploy it it *will* be made available, so use
with care. If you wish your drafts to be not available in your deployed site, you
can set ``DEPLOY_DRAFTS = False`` in your configuration. This will not work if
lazily include ``nikola build`` in your ``DEPLOY_COMMANDS``.
Also if a post has a date in the future, it will not be shown in indexes until
you rebuild after that date. This behavior can be disabled by setting
``FUTURE_IS_NOW = True`` in your configuration, which will make future posts be
published immediately. Posts dated in the future are *not* deployed by default
(when ``FUTURE_IS_NOW = False``). To make future posts available in the
deployed site, you can set ``DEPLOY_FUTURE = True`` in your configuration.
Generally, you want FUTURE_IS_NOW and DEPLOY_FUTURE to be the same value.
Private Posts
~~~~~~~~~~~~~
If you add a "private" tag to a post, then it will not be shown in indexes and feeds.
It *will* be compiled, and if you deploy it it *will* be made available, so it will
not generate 404s for people who had linked to it.
Queuing Posts
~~~~~~~~~~~~~
Some blogs tend to have new posts based on a schedule (for example,
every Mon, Wed, Fri) but the blog authors don't like to manually
schedule their posts. You can schedule your blog posts based on a
rule, by specifying a rule in the ``SCHEDULE_RULE`` in your
configuration. You can either post specific blog posts according to
this schedule by using the ``--schedule`` flag on the ``new_post``
command or post all new posts according to this schedule by setting
``SCHEDULE_ALL = True`` in your configuration. (Note: This feature
requires that the ``FUTURE_IS_NOW`` setting is set to ``False``)
For example, if you would like to schedule your posts to be on every
Monday, Wednesday and Friday at 7am, add the following
``SCHEDULE_RULE`` to your configuration:
.. code:: python
SCHEDULE_RULE = 'RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=7;BYMINUTE=0;BYSECOND=0'
For more details on how to specify a recurrence rule, look at the
`iCal specification <http://www.kanzaki.com/docs/ical/rrule.html>`_.
Say, you get a free Sunday, and want to write a flurry of new posts,
or at least posts for the rest of the week, you would run the
``new_post`` command with the ``--schedule`` flag, as many times as
you want:
.. code:: console
$ nikola new_post --schedule
# Creates a new post to be posted on Monday, 7am.
$ nikola new_post -s
# Creates a new post to be posted on Wednesday, 7am.
$ nikola new_post -s
# Creates a new post to be posted on Friday, 7am.
.
.
.
All these posts get queued up according to your schedule, but note
that you will anyway need to build and deploy your site for the posts
to appear online. You can have a cron job that does this regularly.
Post Types
~~~~~~~~~~
Nikola supports specifying post types, just like Tumblr does. Post
types affect the look of your posts, by adding a ``post-YOURINPUTHERE``
CSS class to the post. Each post can have one and exactly one type. Nikola
styles the following types in the default themes:
.. class:: table table-bordered
+-----------------+----------------------------+------------------+
| Name(s) | Description | Styling |
+=================+============================+==================+
| text | plain text — default value | standard |
+-----------------+----------------------------+------------------+
| micro | “small” (short) posts | big serif font |
+-----------------+----------------------------+------------------+
Indexes
~~~~~~~
All your posts that are not drafts, private or dated in the future, will be
shown in indexes.
Settings
````````
Indexes are put in the ``INDEX_PATH`` directory, which defaults to an empty
string (site root). The “main” index is ``index.html``, and all the further
indexes are ``index-*.html``, respectively.
By default, 10 posts are displayed on an index page. This can be changed with
``INDEX_DISPLAY_POST_COUNT``. Indexes can show full posts or just the teasers,
as controlled by the ``INDEX_TEASERS`` setting (defaults to ``False``).
Titles of the pages can be controlled by using ``INDEXES_TITLES``,
``INDEXES_PAGES`` and ``INDEXES_PAGES_MAIN`` settings.
Categories and tags use simple lists by default that show only titles and
dates; however, you can switch them to full indexes by using
``CATEGORY_PAGES_ARE_INDEXES`` and ``TAG_PAGES_ARE_INDEXES``, respectively.
Something similar happens with authors. To use full indexes in authors, set
``AUTHOR_PAGES_ARE_INDEXES`` to ``True``.
Static indexes
``````````````
Nikola uses *static indexes* by default. This means that ``index-1.html`` has
the oldest posts, and the newest posts past the first 10 are in
``index-N.html``, where ``N`` is the highest number. Only the page with the
highest number and the main page (``index-N.html`` and ``index.html``) are
rebuilt (the others remain unchanged). The page that appears when you click
*Older posts* on the index page, ``index-N.html``, might contain **less than 10
posts** if there are not enough posts to fill up all pages.
This can be disabled by setting ``INDEXES_STATIC`` to ``False``. In that mode,
``index-1.html`` contains all the newest posts past the first 10 and will
always contain 10 posts (unless you have less than 20). The last page,
``index-N.html``, contains the oldest posts, and might contain less than 10
posts. This is how many blog engines and CMSes behave. Note that this will
lead to rebuilding all index pages, which might be a problem for larger blogs
(with a lot of index pages).
Creating a Page
---------------
Pages are the same as posts, except that:
* They are not added to the front page
* They don't appear on the RSS feed
* They use the ``story.tmpl`` template instead of ``post.tmpl`` by default
The default configuration expects the page's metadata and text files to be on the
``stories`` folder, but that can be changed (see ``PAGES`` option above).
You can create the page's files manually or use the ``new_post`` command
with the ``-p`` option, which will place the files in the folder that
has ``use_in_feed`` set to False.
Supported input formats
-----------------------
Nikola supports multiple input formats. Out of the box, we have compilers available for:
* reStructuredText (default and pre-configured)
* `Markdown`_
* `IPython Notebook/Jupyter`_
* `HTML`_
* `PHP`_
* anything `Pandoc`_ supports (including Textile, DocBook, LaTeX, MediaWiki,
TWiki, OPML, Emacs Org-Mode, txt2tags, Microsoft Word .docx, EPUB, Haddock markup)
Plus, we have specialized compilers in the Plugins Index for:
* `AsciiDoc <https://plugins.getnikola.com/#asciidoc>`_
* `BBCode <https://plugins.getnikola.com/#bbcode>`_
* `CommonMark <https://plugins.getnikola.com/#commonmark>`_
* `IRC logs <https://plugins.getnikola.com/#irclogs>`_
* `Markmin <https://plugins.getnikola.com/#markmin>`_
* `MediaWiki (smc.mw) <https://plugins.getnikola.com/#mediawiki>`_
* `Misaka <https://plugins.getnikola.com/#misaka>`_
* `ODT <https://plugins.getnikola.com/#odt>`_
* `Emacs Org-Mode <https://plugins.getnikola.com/#orgmode>`_
* `reST with HTML 5 output <https://plugins.getnikola.com/#rest_html5>`_
* `Textile <https://plugins.getnikola.com/#textile>`_
* `txt2tags <https://plugins.getnikola.com/#txt2tags>`_
* `CreoleWiki <https://plugins.getnikola.com/#wiki>`_
* `WordPress posts <https://plugins.getnikola.com/#wordpress_compiler>`_
Configuring other input formats
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to use input formats other than reStructuredText, you need some extra
setup.
1. Make sure you have the compiler for the input format you want. Some
input formats are supported out-of-the-box, but others must be installed from
the Plugins repository. You may also need some extra dependencies. You
will get helpful errors if you try to build when missing something.
2. You must ensure the compiler and your desired input file extension is included
in the ``COMPILERS`` dict and does not conflict with any other format. This
is extremely important for the pandoc compiler.
3. Finally, you must configure the ``POSTS`` and ``PAGES`` tuples. Follow the
instructions and the format set by pre-existing entries. Make sure to use
the same extension as is set in ``COMPILERS`` and configure the outputs
properly.
Markdown
````````
To use Markdown in your posts/pages, make sure ``markdown`` is in your
``COMPILERS`` and that at least one of your desired extensions is defined in
``POSTS`` and ``PAGES``.
You can use Python-Markdown extensions by setting the ``MARKDOWN_EXTENSIONS``
config option:
.. code:: python
MARKDOWN_EXTENSIONS = ['fenced_code', 'codehilite', 'extra']
Nikola comes with some Markdown Extensions built-in and enabled by default,
namely a gist directive, a podcast directive, and ``~~strikethrough~~`` support.
IPython Notebook/Jupyter
````````````````````````
To use Jupyter notebooks (previously known as IPython Notebooks) as posts/pages,
make sure ``ipynb`` is in your ``COMPILERS`` and that the ``.ipynb`` extension
is defined in ``POSTS`` and ``PAGES``.
The ``-f`` argument to ``new_post`` should be used in the ``ipynb@KERNEL`` format.
It defaults to Python in the version used by Nikola if not specified.
HTML
````
To use plain HTML in your posts/pages, make sure ``html`` is in your
``COMPILERS``
and that the ``.html`` extension is defined in ``POSTS`` and ``PAGES``.
PHP
```
There are two ways of using PHP within Nikola:
1. To use PHP in your posts/pages (inside your site, with the theme and
everything), make sure ``php`` is in your ``COMPILERS`` and that the ``.php``
extension is defined in ``POSTS`` and ``PAGES``.
2. To use PHP as standalone files (without any modifications), put them in
``files/`` (or whatever ``FILES_FOLDERS`` is configured to).
Pandoc
``````
To use Pandoc, you must uncomment the entry in ``COMPILERS`` and set the
extensions list to your desired extensions while also removing them from their
original compilers. The input format is inferred from the extension by Pandoc.
Using Pandoc for reStructuredText, Markdown and other input formats that have a
standalone Nikola plugin is **not recommended** as it disables plugins and
extensions that are usually provided by Nikola.
Shortcodes
----------
This feature is "inspired" (copied wholesale) from `Hugo <https://gohugo.io/extras/shortcodes/>`__ so I will
steal part of their docs too.
A shortcode is a simple snippet inside a content file that Nikola will render using a predefined template or
custom code from a plugin.
To use them from plugins, please see `Extending Nikola <https://getnikola.com/extending.html#shortcodes>`__
Using a shortcode
~~~~~~~~~~~~~~~~~
In your content files, a shortcode can be called by using the ``{{% name parameters %}}`` form. Shortcode parameters are space delimited. Parameters with spaces can be quoted (or backslash escaped).
The first word is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional or both (although you can’t mix parameter types in a single call). The format for named parameters models that of HTML with the format name="value".
Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing shortcodes match (name only), the closing being prepended with a slash.
Example of a paired shortcode (note that we don't have a highlight shortcode yet ;-)::
{{% highlight go %}} A bunch of code here {{% /highlight %}}
Build-in shortcodes
~~~~~~~~~~~~~~~~~~~
post-list
Will show a list of posts, see the `Post List directive for details <#post-list>`__
Template-based shortcodes
~~~~~~~~~~~~~~~~~~~~~~~~~
If you put a template in ``shortcodes/`` called ``mycode.tmpl`` then Nikola will create a shortcode
called ``mycode`` you can use. Any options you pass to the shortcode will be available as variables
for that template. If you use the shortcode as paired, then the contents between the paired tags will
be available in the ``data`` variable.
If you want to access the Nikola object, it will be available as ``site``. Use with care :-)
For example, if your ``shortcodes/foo.tmpl`` contains this::
This uses the bar variable: ${bar}
And your post contains this::
{{% foo bar=bla %}}
Then the output file will contain::
This uses the bar variable: bla
Redirections
------------
If you need a page to be available in more than one place, you can define redirections
in your ``conf.py``:
.. code:: python
# A list of redirection tuples, [("foo/from.html", "/bar/to.html")].
#
# A HTML file will be created in output/foo/from.html that redirects
# to the "/bar/to.html" URL. notice that the "from" side MUST be a
# relative URL.
#
# If you don't need any of these, just set to []
REDIRECTIONS = [("index.html", "/weblog/index.html")]
It's better if you can do these using your web server's configuration, but if
you can't, this will work.
Configuration
-------------
The configuration file is called ``conf.py`` and can be used to customize a lot of
what Nikola does. Its syntax is python, but if you don't know the language, it
still should not be terribly hard to grasp.
The default ``conf.py`` you get with Nikola should be fairly complete, and is quite
commented.
You surely want to edit these options:
.. code:: python
# Data about this site
BLOG_AUTHOR = "Your Name" # (translatable)
BLOG_TITLE = "Demo Site" # (translatable)
SITE_URL = "https://getnikola.com/"
BLOG_EMAIL = "joe@demo.site"
BLOG_DESCRIPTION = "This is a demo site for Nikola." # (translatable)
Some options are demarked with a (translatable) comment above or right next to
them. For those options, two types of values can be provided:
* a string, which will be used for all languages
* a dict of language-value pairs, to have different values in each language
.. note:: It is possible to load the configuration from another file by specifying
``--conf=path/to/other.file`` on Nikola's command line. For example, to
build your blog using the configuration file ``configurations/test.conf.py``,
you have to execute ``nikola build --conf=configurations/test.conf.py``.
Customizing Your Site
---------------------
There are lots of things you can do to personalize your website, but let's see
the easy ones!
CSS tweaking
Using the default configuration, you can create a ``assets/css/custom.css``
file under ``files/`` or in your theme and then it will be loaded from the
``<head>`` blocks of your site pages. Create it and put your CSS code there,
for minimal disruption of the provided CSS files.
If you feel tempted to touch other files in assets, you probably will be better off
with a `custom theme <theming.html>`__.
If you want to use LESS_ or Sass_ for your custom CSS, or the theme you use
contains LESS or Sass code that you want to override, you will need to install
the `LESS plugin <https://plugins.getnikola.com/#less>`__ or
`SASS plugin <https://plugins.getnikola.com/#sass>`__ create a ``less`` or
``sass`` directory in your site root, put your ``.less`` or ``.scss`` files
there and a targets file containing the list of files you want compiled.
.. _LESS: http://lesscss.org/
.. _Sass: http://sass-lang.com/
Template tweaking
If you really want to change the pages radically, you will want to do a
`custom theme <theming.html>`__.
Navigation Links
The ``NAVIGATION_LINKS`` option lets you define what links go in a sidebar or menu
(depending on your theme) so you can link to important pages, or to other sites.
The format is a language-indexed dictionary, where each element is a tuple of
tuples which are one of:
1. A (url, text) tuple, describing a link
2. A (((url, text), (url, text), (url, text)), title) tuple, describing a submenu / sublist.
Example:
.. code:: python
NAVIGATION_LINKS = {
DEFAULT_LANG: (
('/archive.html', 'Archives'),
('/categories/index.html', 'Tags'),
('/rss.xml', 'RSS'),
((('/foo', 'FOO'),
('/bar', 'BAR')), 'BAZ'),
),
}
.. note::
1. Support for submenus is theme-dependent. Only one level of
submenus is supported.
2. Some themes, including the default Bootstrap 3 theme, may
present issues if the menu is too large. (in ``bootstrap3``, the
navbar can grow too large and cover contents.)
3. If you link to directories, make sure to follow ``STRIP_INDEXES``. If
it’s set to ``True``, end your links with a ``/``, otherwise end them
with ``/index.html`` — or else they won’t be highlighted when active.
The ``SEARCH_FORM`` option contains the HTML code for a search form based on
duckduckgo.com which should always work, but feel free to change it to
something else.
Footer
``CONTENT_FOOTER`` is displayed, small at the bottom of all pages, I use it for
the copyright notice. The default shows a text formed using ``BLOG_AUTHOR``,
``BLOG_EMAIL``, the date and ``LICENSE``. Note you need to use
``CONTENT_FOOTER_FORMATS`` instead of regular str.format or %-formatting,
for compatibility with the translatable settings feature.
BODY_END
This option lets you define a HTML snippet that will be added at the bottom of body.
The main usage is a Google analytics snippet or something similar, but you can really
put anything there. Good place for JavaScript.
SOCIAL_BUTTONS_CODE
The ``SOCIAL_BUTTONS_CODE`` option lets you define a HTML snippet that will be added
at the bottom of body. It defaults to a snippet for AddThis, but you can
really put anything there. See `social_buttons.html` for more details.
Fancy Dates
-----------
Nikola can use various styles for presenting dates.