.. title: Nikola Demo Info Pages
.. slug: index
.. date: 2020-04-17 7:00:00 UTC+02:00
.. author: Jean-Michel Chopin
.. link:
.. description:

.. sectnum::

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

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

Nikola Handbook
---------------

* :doc:`<handbook>`
* `Static Site Generator | Nikola - www.getnikola.com/ <https://www.getnikola.com/>`__

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:

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

.. 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|END_TEASER)(:(.+))?\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>'

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.

Using a shortcode
~~~~~~~~~~~~~~~~~

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

  .. code:: text

    {{% raw %}}{{% name parameters %}}{{% /raw %}}

* highlight example

  .. code:: restructuredtext

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

Built-in shortcodes
~~~~~~~~~~~~~~~~~~~

* **emoji** Insert an emoji. For example:
  ``{{% raw %}}{{% emoji crying_face %}}{{% /raw %}}``
  {{% 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:\JMC\dvl\python\prog\WPy64-3820\python-3.8.2.amd64\Lib\site-packages\nikola\plugins\shortcode\emoji\data\
    * 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:
  ``{{% raw %}}{{% media url=https://www.youtube.com/watch?v=8AF-Sm8d8yk %}}{{% /raw %}}``
  {{% media url=https://www.youtube.com/watch?v=8AF-Sm8d8yk %}}

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

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

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

  .. code:: text

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

  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)

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)

.. code:: restructuredtext

  .. sectnum::

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

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

.. sidebar:: Magic Links (sidebar with ``.. sidebar:: title``)

   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``).

   Note that magic links with spaces won’t work with some input formats (eg.
   reST), so you should use slugs there (eg. ``link://tag/some-tag`` instead of
   ``link://tag/Some Tag``)

Specific Admonitions

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

.. warning::

    This a warning directive with ``.. warning::``

.. note::

    note with ``.. note::``

    Keys are converted to lowercase automatically.

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

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

.. admonition:: admonition with ``.. admonition::`` = Shortcodes and reStructuredText

    In reStructuredText shortcodes may fail because docutils turns URL into links and everything breaks.
    For some shortcodes there are alternative docutils directives (example, you can use the media
    **directive** instead of the media shortcode.

    Also, you can use the shortcode **role**:

    .. code:: text

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

    That role passes text unaltered, so shortcodes behave correctly.

``.. code-block:: python``

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

reStructuredText Extensions Includes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Include another RST file

.. code:: restructuredtext

  .. include:: filename_full_path_before_interpretation

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

.. code:: restructuredtext

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

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

.. code:: restructuredtext

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

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

It supports Instagram, Flickr, Github gists, Funny or Die, and dozens more, thanks to `Micawber <https://github.com/coleifer/micawber>`_

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

.. code:: restructuredtext

    .. youtube:: 8AF-Sm8d8yk

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

.. code:: restructuredtext

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

.. youtube:: 8AF-Sm8d8yk

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

.. code:: restructuredtext

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

.. code:: restructuredtext

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

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

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

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

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

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

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:

.. code:: restructuredtext

    .. 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 <https://feimosi.github.io/baguetteBox.js/>`_ by default. All options supported by
the reST `image <http://docutils.sourceforge.net/docs/ref/rst/directives.html#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
<http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure>`_
directive instead:

.. code:: restructuredtext

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

.. code:: html

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

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>```
* :doc:`Creating a theme <creating-a-theme#starting-from-somewhere>`


.. code:: restructuredtext

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

* :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>`

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)

  .. code:: console

    nikola subtheme -n custom_theme_name -s minty -p bootstrap4

Nikola path
-----------

* :doc:`Nikola path-handlers <path-handlers>`
* for the links like ``link://kind/name``

reStructuredText quickref
-------------------------

* :doc:`<quickref>`

Field Lists
~~~~~~~~~~~

* Plain text

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

Literal Blocks
~~~~~~~~~~~~~~

* Plain text

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

Explicit Markup: Footnotes
~~~~~~~~~~~~~~~~~~~~~~~~~~

* Plain text

.. code:: 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 [#]_ and [#]_.

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

Explicit Markup: External Hyperlink Targets
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Plain text

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

  .. _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/>`_.

reStructuredText quickstart
---------------------------

* :doc:`reStructuredText quickstart<quickstart>`

reStructuredText Directives - docutils.sourceforge.io
-----------------------------------------------------

* `reStructuredText Directives - docutils.sourceforge.io/ <https://docutils.sourceforge.io/docs/ref/rst/directives.html>`__

Directives for Substitution Definitions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Replacement Text
<<<<<<<<<<<<<<<<

:Directive Type:	"replace"
:Doctree Element:	Text & inline elements
:Directive Arguments:	None.
:Directive Options:	None.
:Directive Content:	A single paragraph; may contain inline markup.

The "replace" directive is used to indicate replacement text for a substitution reference. It may be used within substitution definitions only. For example, this directive can be used to expand abbreviations:

.. code:: restructuredtext

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

  .. |reST| replace:: reStructuredText

Rendered

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

.. |reST| replace:: reStructuredText

As reStructuredText doesn't support nested inline markup, the only way to create a reference with styled text is to use substitutions with the "replace" directive:

.. code:: restructuredtext

  I recommend you try |Python|_.

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

Rendered

I recommend you try |Python|_.

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

reStructuredText Primer — Sphinx 4.0.0+ documentation
-----------------------------------------------------

* `reStructuredText Primer — Sphinx 4.0.0+ documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__

Nikola Theming Documentation
----------------------------
* :doc:`<theming>`
* :doc:`<creating-a-theme>`
* :doc:`<bootstrap-demo>`

Nikola specials Documentation
-----------------------------
* :doc:`<internals>`
* :doc:`<extending>`
* :doc:`<charts>`
* :doc:`<listings-demo>`
* :doc:`<social_buttons>`

Miscellaneous
-------------
* :doc:`<about_nikola>`
* :doc:`<dr-nikolas-vendetta>`