Nikola Demo Info Pages

1.1 Creating a Blog Post: 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" TEASER_END or END_TEASER in your post.

In reStructuredText:

.. TEASER_END

In Markdown (or basically, the resulting HTML of any format):

<!-- 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 behavior 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:

.. 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:

import re
TEASER_REGEXP = re.compile('<!--\s*(more|TEASER_END|END_TEASER)(:(.+))?\s*-->', re.IGNORECASE)

Or you can completely customize the link using the READ_MORE_LINK option.

# 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>'

1.2 Images versus Figures

A "figure" consists of image data (including image options), an optional caption (a single paragraph), and an optional legend (arbitrary body elements). For page-based output media, figures might float to a different position if this helps the page layout.

1.3 Using a shortcode

• In your content files, a shortcode can be called by using this form:

  {{% name parameters %}}
  

• highlight example

  {{% highlight python %}} A bunch of code here {{% /highlight %}}
  

1.4 Built-in shortcodes

• emoji Insert an emoji. For example: {{% emoji crying_face %}} 😢

  • GitHub - shanraisshan/EmojiCodeSheet: Your first stop for developing emoji keyboards for any platform, using any language. - github.com/ [[https://github.com/shanraisshan/EmojiCodeSheet]] (20200419_045755)

    • EmojiCodeSheet/json/string at master · shanraisshan/EmojiCodeSheet · GitHub - github.com/ [[https://github.com/shanraisshan/EmojiCodeSheet/tree/master/json/string]] (20200419_050310)

    • Files stored in A:JMCdvlpythonprogWPy64-3820python-3.8.2.amd64Libsite-packagesnikolapluginsshortcodeemojidata

    • Activity.json

    • Flags.json

    • Food.json

    • LICENSE

    • Nature.json

    • Objects.json

    • People.json

    • Symbols.json

    • Travel.json

• media Display media embedded from a URL, for example, this will embed a youtube video: {{% media url=https://www.youtube.com/watch?v=8AF-Sm8d8yk %}}

  In order to use the media directive, you must install the "micawber" Python package.

• thumbnail Display image thumbnails, with optional captions. Examples:

  {{% thumbnail "/images/foo.png" %}}{{% /thumbnail %}}
  {{% thumbnail "/images/foo.png" alt="Foo Image" align="center" %}}{{% /thumbnail %}}
  {{% thumbnail "/images/foo.png" imgclass="image-grayscale" figclass="figure-shadow" %}}<p>Image caption</p>{{% /thumbnail %}}
  {{% thumbnail "/images/foo.png" alt="Foo Image" title="Insert title-text joke here" align="right" %}}<p class="caption">Foo Image (right-aligned) caption</p>{{% /thumbnail %}}
  

  The following keyword arguments are supported:

  • alt (alt text for image)

  • align (image alignment, left/center/right)

  • linktitle (title text for the link, shown by e.g. baguetteBox)

  • title (title text for image)

  • imgclass (class for image)

  • figclass (class for figure, used only if you provide a caption)

1.5 reStructuredText Extensions

The following sets the sections numbering and creates a table of contents floating on the right (and sections have a backling to the toc entry)

.. sectnum::

.. class:: alert alert-primary float-md-right

.. contents:: Table of Contents
  :backlinks: entry

Specific Admonitions

Directive Types: "attention", "caution", "danger", "error", "hint", "important", "note", "tip", "warning", "admonition"

.. Note to editors: the paragraph below uses U+200B, zero-width space. Don’t break it.

:sc:`{{% shortcode here %}}`

.. code-block:: python

TWITTER_CARD = {
    'use_twitter_cards': True,  # enable Twitter Cards
    'card': 'summary',          # Card type, you can also use 'summary_large_image',
                                # see https://dev.twitter.com/cards/types
    'site': '@website',         # twitter nick for the website
    'creator': '@username',     # Username for the content creator / author.
}

1.6 reStructuredText Extensions Includes

Include another RST file

.. include:: filename_full_path_before_interpretation

1.7 reStructuredText Extensions Media

In order to use the media directive, you must install the "micawber" Python package.

This directive lets you embed media from a variety of sites automatically by just passing the URL of the page. For example here are two random videos:

Bigflo et Oli: dommage

.. media:: https://www.youtube.com/watch?v=8AF-Sm8d8yk

.. media:: https://vimeo.com/233190141

It supports Instagram, Flickr, Github gists, Funny or Die, and dozens more, thanks to Micawber

1.8 reStructuredText Extensions YouTube

To link to a YouTube video, you need the id of the video. For example, if the URL of the video is http://www.youtube.com/watch?v=8N_tupPBtWQ what you need is 8N_tupPBtWQ

Once you have that, all you need to do is:

Bigflo et Oli: dommage

.. youtube:: 8AF-Sm8d8yk

Supported options: height, width, align (one of left, center, right) — all are optional. Example:

.. youtube:: 8AF-Sm8d8yk
   :align: center

1.9 reStructuredText Extensions 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

Once you have that, all you need to do is:

Bigflo et Oli: dommage

.. vimeo:: 233190141

If you have internet connectivity when generating your site, the height and width of the embedded player will be set to the native height and width of the video. You can override this if you wish:

.. vimeo:: 233190141
   :height: 240
   :width: 320

Supported options: height, width, align (one of left, center, right) — all are optional.

1.10 reStructuredText Extensions Code

The code directive has been included in docutils since version 0.9 and now replaces Nikola's code-block directive. To ease the transition, two aliases for code directive are provided: code-block and sourcecode:

.. code-block:: python
   :number-lines:

   print("Our virtues and our failings are inseparable")

1.11 reStructuredText Extensions Thumbnails

To include an image placed in the images folder (or other folders defined in IMAGE_FOLDERS), use the thumbnail directive, like this:

.. thumbnail:: /images/tesla.jpg
   :alt: Nikola Tesla

The small thumbnail will be placed in the page, and it will be linked to the bigger version of the image when clicked, using baguetteBox by default. All options supported by the reST image directive are supported (except target). Providing alt is recommended, as this is the image caption. If a body element is provided, the thumbnail will mimic the behavior of the figure directive instead:

.. thumbnail:: /images/tesla.jpg
   :alt: Nikola Tesla

   Nikola Tesla, the man that invented the 20th century.

If you want to include a thumbnail in a non-reST post, you need to produce at least this basic HTML:

<a class="reference" href="images/tesla.jpg" alt="Nikola Tesla"><img src="images/tesla.thumbnail.jpg"></a>

1.12 reStructuredText Extensions Role doc

In Nikola, this role works only with pages but not with posts

• :doc:`my text  <my-slug#m-anchor>`

• :doc:`creating a theme <creating-a-theme#starting-from-somewhere>`

• Creating a theme

* :doc:`Read the manual <handbook>`
* `Visit the Nikola website to learn more <https://getnikola.com>`__
* `See a demo photo gallery <link://gallery/demo>`__
* :doc:`See a demo listing <listings-demo>`
* :doc:`listings-demo` showing the title
* :doc:`See a demo of a longer text <dr-nikolas-vendetta>`

Rendered

• Read the manual

• Visit the Nikola website to learn more

• See a demo photo gallery

• See a demo listing

• Listings Demo showing the title

• See a demo of a longer text

1.13 Custom Themes

• Bootswatch: Free themes for Bootstrap https://bootswatch.com/

• 20200419 JMC To install bootstrap4-minty

  • Bootswatch: Minty - bootswatch.com https://bootswatch.com/minty/ (20200420_081536)

  nikola subtheme -n custom_theme_name -s minty -p bootstrap4
  

3.1 Field Lists

• Plain text

:Authors:
    Tony J. (Tibs) Ibbs,
    David Goodger

    (and sundry other good-natured folks)

:Version: 1.0 of 2001/08/08
:Dedication: To my father.

• Typical result

  Authors

  Tony J. (Tibs) Ibbs, David Goodger

  (and sundry other good-natured folks)

  Version

  1.0 of 2001/08/08

  Dedication

  To my father.

3.2 Literal Blocks

• Plain text

Literal blocks end when text returns to
the preceding paragraph's indentation.
This means that something like this
is possible::

      We start here
    and continue here
  and end here.

• Typical result

  Literal blocks end when text returns to the preceding paragraph's indentation. This means that something like this is possible:

      We start here
    and continue here
  and end here.

3.3 Explicit Markup: Footnotes

• Plain text

Footnote references, like [5]_.
Note that footnotes may get
rearranged, e.g., to the bottom of
the "page".

.. [5] A numerical footnote. Note
  there's no colon after the ``]``.

Autonumbered footnotes are
possible, like using [#]_ and [#]_.

.. [#] This is the first one.
.. [#] This is the second one.

• Typical result

  Footnote references, like 5. Note that footnotes may get rearranged, e.g., to the bottom of the "page".

  5

  A numerical footnote. Note there's no colon after the ].

  Autonumbered footnotes are possible, like using 1 and 2.

  1

  This is the first one.

  2

  This is the second one.

3.4 Explicit Markup: External Hyperlink Targets

• Plain text

External hyperlinks, like Python_.

.. _Python: http://www.python.org/

reStructuredText also provides for embedded URIs (details), a convenience at the expense of readability.
A hyperlink reference may directly embed a target URI inline, within angle brackets.

External hyperlinks with embed target URI, like `Python
<http://www.python.org/>`_.

• Typical result

  External hyperlinks, like Python.

  reStructuredText also provides for embedded URIs (details), a convenience at the expense of readability. A hyperlink reference may directly embed a target URI inline, within angle brackets.

  External hyperlinks with embed target URI, like Python.

5.1 Directives for Substitution Definitions

Yes, |reST| is a long word, so I can't blame anyone for wanting to
abbreviate it.

.. |reST| replace:: reStructuredText

I recommend you try |Python|_.

.. |Python| replace:: Python, *the* best language around
.. _Python: http://www.python.org/