Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
update docs
Signed-off-by: Chris Warrick <kwpolska@gmail.com>
  • Loading branch information
Kwpolska committed Jan 13, 2015
1 parent 21bfb8f commit de3727e
Show file tree
Hide file tree
Showing 11 changed files with 419 additions and 153 deletions.
194 changes: 155 additions & 39 deletions listings/conf.py

Large diffs are not rendered by default.

89 changes: 88 additions & 1 deletion stories/CHANGES.txt
@@ -1,3 +1,90 @@
New in v7.3.0
=============

Features
--------

* Added ``-a``, ``--author`` option to set post author field
* Added option INDEXES_PRETTY_PAGE_URL to make URLs for indexes
pages more pretty. (Issue #1548)
* Added ``-i``, ``--import`` argument to ``new_post`` for importing
existing post contents (Issue #1385)
* Added warning about ``password`` in posts being insecure
(Issue #1547)
* INDEXES_TITLE and INDEXES_PAGES are translatable (Issue #1544)
* Added new option ARCHIVES_ARE_INDEXES which allows archive pages
which list posts to be rendered with the post contents.
(Issue #1537)
* Added new option INDEXES_STATIC which allows to define the
page ordering for indexes (Issue #1537). Also, if tag pages are
created as indexes, they will behave more close to the
default indexes.
* Use ``table`` line-numbering style with reST code, making
copy-pasting code possible (Issue #1285)
* Tag and category pages are now more separated. The prefix for
category pages can be changed and the folder can be modified
independently of the tags' folder. (Issue #1535)
* Writing the tag cloud data file can now be disabled. Will be
disabled by default in the future. (Issue #1535)
* The ``utils.config_changed`` function now takes an optional extra
argument, ``identifier``, used to identify the source of a specific
dependency save. As such, ALL your files will be rebuilt after
upgrading. (Issue #1526 via #1521)
* New option GALLERY_FOLDERS replacing GALLERY_PATH (Issue #1511)
* New PANDOC_OPTIONS option (Issue #1492)
* New tab-width option in code-block directive (Issue #1514)
* New option TAG_PAGES_DESCRIPTIONS for optionally making individual
tag pages more unique and interesting (Issue #1486)
* New option LISTINGS_FOLDERS (which replaces LISTINGS_FOLDER) which
allows to separate input and output folder names for listings, and
allows to have more than one listings folder (Issue #1499)
* ReST listing directive now honors alternative listings folder names
(Issue #1499)
* New command line option --conf= to specify the configuration file
(default is conf.py) (Issue #1501)
* Added Arabic translation (by darkwise)
* Added Danish translation (by mikkelkristiansen)
* Added Indonesian translation (by Willy Sudiarto Raharjo)
* Added Korean translation (by Dong Geun)
* Added Serbian translation (by Ivan Radeljic)
* Added Swedish translation (by Johan Sommerfeld)
* New advanced option RSS_LINKS_APPEND_QUERY for tracking traffic
from RSS subscribers
* Add ``robots`` meta tag with value ``noindex`` for drafts
(Issue #1489)
* New option TAGLIST_MINIMUM_POSTS allows hiding unpopular tags from
the tag index page (Issue #1484)
* New options CREATE_FULL_ARCHIVES and CREATE_DAILY_ARCHIVE which
allow to create non-hierarchical archives and archives for days,
respectively (Issue #1494)
* New plugin for creating image thumbnails, and a corresponding reST
plugin (Issue #1527)

Bugfixes
--------

* Handle over-and-under-lined titles in rst for guessing title (Issue #1539)
* Don't apply colorbox to figures if they are of islink class. (Issue #1536)
* Turned minify_lines into a no-op (Issue #1497)
* Don’t classify unpublished posts as pages (Issue #1577)
* Fixed a ``TranslatableSetting.langformat`` race condition
* Fixed ``TranslatableSetting`` instantiation in
``TranslatableSetting.langformat`` (Issue #1571)
* Fixed ``rss.xsl`` path for blogs not deployed to server root
(Issue #1563)
* Respect SHOW_UNTRANSLATED_POSTS = False in archives
and for untranslated source files (Issue #1360)
* Make sure drafts don’t appear in sitemaps with multiple languages
(Issue #1489)
* Make site.posts_per_file cover all languages (Issues #1270, #1489)
* Fix ANNOTATIONS not working at all (Issue #1477)
* Fix asking questions with Unicode chars in Python 2 (Issue #1476)
* Use ADDITIONAL_METADATA with the two-file format (Issue #1471)
* Make previewimage compatible with sites deployed to subdirectories
(Issue #1473)
* Make sitemaps work on sites deployed to subdirectories
(Issue #1472)

New in v7.2.0 New in v7.2.0
============= =============


Expand Down Expand Up @@ -655,7 +742,7 @@ Bugfixes
* Added .rst to the default reStructuredText extensions (via Issue #542) * Added .rst to the default reStructuredText extensions (via Issue #542)
* Moved the sample site to the new one-file format (Issue #542) * Moved the sample site to the new one-file format (Issue #542)
* Escape HTML in titles (Issue #537) * Escape HTML in titles (Issue #537)
* Fixed issues with index pages indices (Issue #532) * Fixed issues with index pages indexes (Issue #532)
* Fixed IPython plugin to work with the latest IPython.nbconvert machinery * Fixed IPython plugin to work with the latest IPython.nbconvert machinery
* Fixed failing build because of hidden folders and files inside post folder * Fixed failing build because of hidden folders and files inside post folder


Expand Down
4 changes: 2 additions & 2 deletions stories/conf.txt
@@ -1,9 +1,9 @@
.. title: Nikola v7.2.0 configuration file .. title: Nikola v7.3.0 configuration file
.. slug: conf .. slug: conf
.. date: 2014-11-08 18:51:30 UTC .. date: 2014-11-08 18:51:30 UTC
.. description: The Nikola configuration file. .. description: The Nikola configuration file.
.. type: text .. type: text


The default config file for Nikola v7.2.0 is reproduced below. The default config file for Nikola v7.3.0 is reproduced below.


.. listing:: conf.py python .. listing:: conf.py python
76 changes: 38 additions & 38 deletions stories/creating-a-site.txt
@@ -1,5 +1,5 @@
.. slug: creating-a-site-not-a-blog-with-nikola .. slug: creating-a-site-not-a-blog-with-nikola
.. date: 2013/03/01 12:49:41 .. date: 2015-01-10 10:00:00 UTC
.. tags: nikola, python .. tags: nikola, python
.. link: .. link:
.. description: .. description:
Expand All @@ -10,19 +10,22 @@ Creating a Site (Not a Blog) with Nikola


.. class:: lead .. class:: lead


One of the most frequent questions I get about Nikola is "but how do One of the most frequent questions I get about Nikola is but how do
I create a site that's not a blog?". And of course, that's because the I create a site thats not a blog?. And of course, thats because the
documentation is heavily blog-oriented. This document will change that ;-) documentation is heavily blogoriented. This document will change that ;-)


Since it started, Nikola has had the capabilities to create generic sites. For example, Since it started, Nikola has had the capabilities to create generic sites. For example,
Nikola's `own site <http://getnikola.com>`_ is a fairly generic one. Let's go Nikolas `own site <https://getnikola.com/>`_ is a fairly generic one. Lets go
step by step on how you can do something like that. 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 As usual when starting a nikola site, you start with ``nikola init`` which creates a
empty semi-configured site:: empty (mostly) configured site::


$ nikola init mysite $ nikola init mysite
Created empty site at mysite. Creating Nikola Site
====================
[1970-01-01T00:00:00Z] INFO: init: Created empty site at mysite.


Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py`` Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py``
configuration file: configuration file:
Expand All @@ -40,8 +43,8 @@ configuration file:
BLOG_TITLE = "Not a Blog" BLOG_TITLE = "Not a Blog"
# This is the main URL for your site. It will be used # This is the main URL for your site. It will be used
# in a prominent link # in a prominent link
SITE_URL = "http://notablog.ralsina.com.ar/" SITE_URL = "http://getnikola.com/"
BLOG_EMAIL = "ralsina@kde.org" BLOG_EMAIL = "ralsina@example.com"
BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola." BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola."


# #
Expand All @@ -58,12 +61,13 @@ configuration file:


And now we are ready to create our first page:: And now we are ready to create our first page::


$ nikola new_post -p $ nikola new_page
Creating New Post Creating New Page
----------------- -----------------


Enter title: index Title: index
Your post's text is at: pages/index.txt 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. .. note:: The ``-p`` option in the ``nikola new_post`` command means we are creating a page and not a blog post.


Expand All @@ -74,32 +78,30 @@ We can now build and preview our site::
. render_site:output/categories/index.html . render_site:output/categories/index.html
. render_sources:output/index.txt . render_sources:output/index.txt
. render_rss:output/rss.xml . render_rss:output/rss.xml
:
:
: [Much more of the same]

$ nikola serve $ nikola serve
Serving HTTP on 127.0.0.1 port 8000 ... [1970-01-01T00:00:00Z] INFO: serve: Serving HTTP on 0.0.0.0 port 8000...



And you can see your (very empty) site in http://localhost:8000 And you can see your (very empty) site in http://localhost:8000/


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


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


.. title: index .. title: index
.. slug: index .. slug: index
.. date: 2013/03/01 10:26:17 .. date: 1970-01-01 00:00:00 UTC
.. tags: .. tags:
.. link: .. link:
.. description: .. description:




Write your post here. Write your post here.


Title is the page title, slug is the name of the generated HTML file ``title`` is the page title, ``slug`` is the name of the generated HTML file
(in this case it would be ``index.html``) the date doesn't matter much in (in this case it would be ``index.html``). ``date``, ``tags`` and ``link``
not-blogs, same for tags and link. Description is useful for SEO purposes doesn’t matter at all in stories. ``description`` is useful for SEO purposes
if you care for that. if you care for that.


And below, the content. By default you are expected to use And below, the content. By default you are expected to use
Expand All @@ -108,32 +110,31 @@ Nikola supports a ton of formats, including Markdown, plain HTML, BBCode,
Wiki, and Textile. Wiki, and Textile.


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


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


.. title: Welcome To The Fake Site .. title: Welcome To The Fake Site
.. slug: index .. slug: index
.. date: 2013/03/01 10:26:17 .. date: 1970-01-01 00:00:00 UTC
.. tags: .. tags:
.. link: .. link:
.. description: Fake Site version 1, welcome page! .. description: Fake Site version 1, welcome page!




.. class:: hero-unit span6 .. class:: jumbotron col-md-6


.. admonition:: This is a Fake Site .. admonition:: This is a Fake Site


It pretends to be about things, but is really just an example. It pretends to be about things, but is really just an example.
So, don't click this button, it leads nowhere.


.. class:: btn .. raw:: html


Click Me! <a href="https://getnikola.com/" class="btn btn-primary btn-lg">Click Me!</a>




.. class:: span5 .. class:: col-md-5


Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis.
Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque
Expand All @@ -146,15 +147,13 @@ you can use anything you like from it:
aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos
himenaeos. himenaeos.


[And more in the same vein]

.. admonition:: TIP: Nice URLs .. admonition:: TIP: Nice URLs


If you like your URLs without the ".html" then you want to create folders and 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.


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


Expand All @@ -167,9 +166,10 @@ or whatever.
POSTS = [("posts/*.txt", "blog", "post.tmpl", True)] POSTS = [("posts/*.txt", "blog", "post.tmpl", True)]


Create a post with ``nikola new_post`` and that's it, you now have a blog Create a post with ``nikola new_post`` and that's it, you now have a blog
in http://yoursite.com/blog (you may want to add links to it in NAVIGATION_LINKS of course). in the ``/blog/`` subdirectory of your site — you may want to link to
it in ``NAVIGATION_LINKS``.


You can see the finished site in http://notablog.ralsina.com.ar and its full configuration in If you want to see a site implementing all of the above, check out `the Nikola
http://ralsina.me/listings/notablog/conf.py.html website <https://getnikola.com/>`_.


I hope this was helpful! I hope this was helpful!
4 changes: 4 additions & 0 deletions stories/creating-a-theme.txt
Expand Up @@ -17,6 +17,10 @@ so we get good support for slides and galleries.


I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <http://wordpress.org/themes/monospace>`_. I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <http://wordpress.org/themes/monospace>`_.


.. danger::

This document is outdated! Recommendations in this post may not work!

.. TEASER_END .. TEASER_END


Starting The Theme Starting The Theme
Expand Down
2 changes: 1 addition & 1 deletion stories/extending.txt
Expand Up @@ -8,7 +8,7 @@
Extending Nikola Extending Nikola
================ ================


:Version: 7.2.0 :Version: 7.3.0
:Author: Roberto Alsina <ralsina@netmanagers.com.ar> :Author: Roberto Alsina <ralsina@netmanagers.com.ar>


.. class:: alert alert-info pull-right .. class:: alert alert-info pull-right
Expand Down
2 changes: 1 addition & 1 deletion stories/getting-help.txt
Expand Up @@ -3,7 +3,7 @@
.. date: 1970-01-01 15:00:00 .. date: 1970-01-01 15:00:00
.. description: Get help using Nikola, or contact us. .. description: Get help using Nikola, or contact us.


:Version: 7.2.0 :Version: 7.3.0


.. class:: alert alert-info pull-right .. class:: alert alert-info pull-right


Expand Down

0 comments on commit de3727e

Please sign in to comment.