Skip to content

Commit

Permalink
Update handbook and creating-a-site pages
Browse files Browse the repository at this point in the history 
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
@Kwpolska
Kwpolska committed Jul 16, 2016
1 parent bb7aa8f commit a4c32fa
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 36 deletions.
55 changes: 32 additions & 23 deletions stories/creating-a-site.txt
View file
Expand Up @@ -20,7 +20,9 @@ Nikola’s `own site <https://getnikola.com/>`_ is a fairly generic one. Let’s
step by step on how you can do something like that.

As usual when starting a nikola site, you start with ``nikola init`` which creates a
empty (mostly) configured site::
empty (mostly) configured site:

.. code:: console

$ nikola init mysite
Creating Nikola Site
Expand All @@ -31,13 +33,7 @@ empty (mostly) configured site::
Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py``
configuration file:

.. code-block:: python


##############################################
# Configuration, please edit
##############################################

.. code:: python

# Data about this site
BLOG_AUTHOR = "Roberto Alsina"
Expand All @@ -52,15 +48,21 @@ configuration file:
# Some things in the middle you don't really need to change...
#

POSTS = []
PAGES = [("pages/*.txt", "", "story.tmpl")]
POSTS = ()
# you can also keep the current content of POSTS if you want a blog with your site
PAGES = (
("stories/*.rst", "", "story.tmpl"),
("stories/*.txt", "", "story.tmpl"),
("stories/*.html", "", "story.tmpl"),
)

# And to avoid a conflict because blogs try to generate /index.html
INDEX_PATH = "blog"


And now we are ready to create our first page:

And now we are ready to create our first page::
.. code:: console

$ nikola new_page
Creating New Page
Expand All @@ -70,9 +72,9 @@ And now we are ready to create our first page::
Scanning posts....done!
[1970-01-01T00:00:00Z] INFO: new_page: Your page's text is at: stories/index.rst

.. note:: The ``-p`` option in the ``nikola new_post`` command means we are creating a page and not a blog post.
We can now build and preview our site:

We can now build and preview our site::
.. code:: console

$ nikola build
Scanning posts.done!
Expand All @@ -88,7 +90,7 @@ And you can see your (very empty) site in http://localhost:8000/

So, what’s in that ``pages/index.txt`` file?

.. code-block:: rest
.. code:: rest

.. title: index
.. slug: index
Expand All @@ -105,16 +107,18 @@ So, what’s in that ``pages/index.txt`` file?
doesn’t matter at all in stories. ``description`` is useful for SEO purposes
if you care for that.

And below, the content. By default you are expected to use
`reStructuredText <https://getnikola.com/quickstart.html>`_ but
Nikola supports a ton of formats, including Markdown, plain HTML, BBCode,
Wiki, and Textile.
And below, the content. By default Nikola uses
`reStructuredText <https://getnikola.com/quickstart.html>`_ but it supports
a ton of formats, including Markdown, plain HTML, Jupyter Notebooks, BBCode,
Wiki, and Textile. We will use reStructuredText for this example, but some
people might find it a bit too limiting — if that is the case, try using HTML
for your pages (Nikola does this on the index page, for example).

So, let's give the page a nicer title, and some fake content. Since the default
Nikola theme (called ``bootstrap3``) is based on `Bootstrap <http://getbootstrap.com/>`_
you can use anything you like from it:

.. code-block:: rest
.. code:: rest

.. title: Welcome To The Fake Site
.. slug: index
Expand Down Expand Up @@ -151,20 +155,25 @@ you can use anything you like from it:
.. admonition:: TIP: Nice URLs

If you like your URLs without the ``.html`` then you want to create folders and
put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option.
put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option
(on by default)

And that's it. You will want to change the NAVIGATION_LINKS option to create a reasonable
menu for your site, you will want to modify the theme (check ``nikola help bootswatch_theme``
menu for your site, you may want to modify the theme (check ``nikola help bootswatch_theme``
for a quick & dirty solution), and you may want to add a blog later on, for company news
or whatever.

.. admonition:: TIP: So, how do I add a blog now?

First, change the ``POSTS`` option like this:

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

POSTS = [("posts/*.txt", "blog", "post.tmpl", True)]
POSTS = (
("posts/*.rst", "blog", "post.tmpl"),
("posts/*.txt", "blog", "post.tmpl"),
("posts/*.html", "blog", "post.tmpl"),
)

Create a post with ``nikola new_post`` and that's it, you now have a blog
in the ``/blog/`` subdirectory of your site — you may want to link to
Expand Down
46 changes: 33 additions & 13 deletions stories/manual.txt
View file
Expand Up @@ -233,9 +233,9 @@ 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.
Please note that Nikola does not support encodings other than UTF-8. Make sure
to convert your input files to that encoding to avoid issues. 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
Expand Down Expand Up @@ -332,6 +332,13 @@ to your configuration:

More information: `Issue #1547 <https://github.com/getnikola/nikola/issues/1547>`_

pretty_url
Set to "False" to disable pretty URL for this page. Example:

.. code:: restructuredtext

.. pretty_url: False

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
Expand Down Expand Up @@ -415,19 +422,25 @@ add support for more languages, check out `the Transifex page for Nikola <https:
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:
How does Nikola decide where posts should go?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The place where the post will be placed by ``new_post`` (the first one that
matches the given format) and the final post destination (the first one that
matches a given file) is based on the ``POSTS`` and ``PAGES`` configuration
options. The exact mechanism is explained above the config options in the
``conf.py`` file, and also reproduced below:

.. 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).
# The wildcard is used to generate a list of post source files
# (whatever/thing.rst, for example).
#
# 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
# whatever/thing.es.rst and whatever/thing.es.meta
#
# This assumes you use the default TRANSLATIONS_PATTERN.
#
Expand All @@ -436,22 +449,26 @@ and ``PAGES`` configuration options:
#
# These files are combined with the template to produce rendered
# pages, which will be placed at
# output / TRANSLATIONS[lang] / destination / pagename.html
# output/TRANSLATIONS[lang]/destination/pagename.html
#
# where "pagename" is the "slug" specified in the metadata file.
# The page might also be placed in /destinstion/pagename/index.html
# if PRETTY_URLS are enabled.
#
# 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.
# to feeds, indexes, tag lists and archives 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"),
("posts/*.txt", "posts", "post.tmpl"),
("posts/*.html", "posts", "post.tmpl"),
)
PAGES = (
("stories/*.txt", "stories", "story.tmpl"),
("stories/*.rst", "stories", "story.tmpl"),
("stories/*.txt", "stories", "story.tmpl"),
("stories/*.html", "stories", "story.tmpl"),
)

.. note:: POSTS and PAGES are not flat!
Expand All @@ -462,6 +479,9 @@ and ``PAGES`` configuration options:

If you have ``PRETTY_URLS`` enabled, that would be ``output/posts/foo/bar/index.html``.

The ``new_post`` command
~~~~~~~~~~~~~~~~~~~~~~~~

``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
Expand Down

0 comments on commit a4c32fa

Please sign in to comment.