diff options
| author |   Agustin Henze <tin@sluc.org.ar> | 2012-12-12 19:58:42 -0300 |
|---|---|---|
| committer | Agustin Henze <tin@sluc.org.ar> | 2012-12-12 19:58:42 -0300 |
| commit | ca1f5a392261a7c6b82b5ac1015427605909d8c9 (patch) | |
| tree | f91146c9340c6c78e84aaf6b92053386397e2069 /nikola/data/samplesite | |
Imported Upstream version 4.0.3upstream/4.0.3
Diffstat (limited to 'nikola/data/samplesite')
29 files changed, 3664 insertions, 0 deletions
diff --git a/nikola/data/samplesite/README.txt b/nikola/data/samplesite/README.txt new file mode 100644 index 0000000..ca94b34 --- /dev/null +++ b/nikola/data/samplesite/README.txt @@ -0,0 +1,31 @@ +How To make This Work +--------------------- + +The full manual is in stories/manual.txt, but here is the very short version: + +1. Install docutils (http://docutils.sourceforge.net) +2. Install Mako (http://makotemplates.org) +3. Install doit (http://python-doit.sourceforge.net) +4. Install PIL (http://www.pythonware.com/products/pil/) +5. Install Pygments (http://pygments.org/) +6. Install unidecode (http://pypi.python.org/pypi/Unidecode/) +7. Install lxml (http://lxml.de/) + +To build or update the demo site run this command in the nikola's folder:: + + doit + +To see it:: + + doit serve -p 8000 + +And point your browser to http://localhost:8000 + +Notes on Requirements +--------------------- + +If you don't have PIL, then image galleries will be inefficient because Nikola +will not generate thumbnails. Alternatively, you may install pillow instead of +PIL. + +If you don't have pygments, the code-block directive will not highlight syntax. diff --git a/nikola/data/samplesite/conf.py b/nikola/data/samplesite/conf.py new file mode 100755 index 0000000..4389f03 --- /dev/null +++ b/nikola/data/samplesite/conf.py @@ -0,0 +1,274 @@ +# -*- coding: utf-8 -*- + +import os + +######################################## +# Configuration, please edit +######################################## + +# Data about this site +BLOG_AUTHOR = "Your Name" +BLOG_TITLE = "Demo Site" +BLOG_URL = "http://nikola.ralsina.com.ar" +BLOG_EMAIL = "joe@demo.site" +BLOG_DESCRIPTION = "This is a demo site for Nikola." + +# post_pages contains (wildcard, destination, template, use_in_feed) tuples. +# +# The wildcard is used to generate a list of reSt source files +# (whatever/thing.txt). +# That fragment must have an associated metadata file (whatever/thing.meta), +# and opcionally translated files (example for spanish, with code "es"): +# whatever/thing.txt.es and whatever/thing.meta.es +# +# 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 combinated with the template to produce rendered +# pages, which will be placed at +# output / TRANSLATIONS[lang] / destination / pagename.html +# +# where "pagename" is specified in the metadata file. +# +# if use_in_feed is True, then those posts will be added to the site's +# rss feeds. +# + +post_pages = ( + ("posts/*.txt", "posts", "post.tmpl", True), + ("stories/*.txt", "stories", "story.tmpl", False), +) + +# One or more folders containing files to be copied as-is into the output. +# The format is a dictionary of "source" "relative destination". +# Default is: +# FILES_FOLDERS = {'files': '' } +# Which means copy 'files' into 'output' + +# A mapping of languages to file-extensions that represent that language. +# Feel free to add or delete extensions to any list, but don't add any new +# compilers unless you write the interface for it yourself. +# +# 'rest' is reStructuredText +# 'markdown' is MarkDown +# 'html' assumes the file is html and just copies it +#post_compilers = { +# "rest": ('.txt', '.rst'), +# "markdown": ('.md', '.mdown', '.markdown') +# "html": ('.html', '.htm') +# } + +# Nikola is multilingual! +# +# Currently supported languages are: +# English -> en +# Greek -> gr +# German -> de +# French -> fr +# Russian -> ru +# Spanish -> es +# Italian -> it +# +# If you want to use Nikola with a non-supported language you have to provide +# a module containing the necessary translations +# (p.e. look at the modules at: ./nikola/data/themes/default/messages/fr.py). +# If a specific post is not translated to a language, then the version +# in the default language will be shown instead. + +# What is the default language? +DEFAULT_LANG = "en" + +# What other languages do you have? +# The format is {"translationcode" : "path/to/translation" } +# the path will be used as a prefix for the generated pages location +TRANSLATIONS = { + DEFAULT_LANG: "", + #"gr": "./gr", + #"de": "./de", + #"fr": "./fr", + #"ru": "./ru", + #"es": "./es", + } + +# Paths for different autogenerated bits. These are combined with the +# translation paths. + +# Final locations are: +# output / TRANSLATION[lang] / TAG_PATH / index.html (list of tags) +# output / TRANSLATION[lang] / TAG_PATH / tag.html (list of posts for a tag) +# output / TRANSLATION[lang] / TAG_PATH / tag.xml (RSS feed for a tag) +TAG_PATH = "categories" + +# If TAG_PAGES_ARE_INDEXES is set to True, each tag's page will contain +# the posts themselves. If set to False, it will be just a list of links. +TAG_PAGES_ARE_INDEXES = True + +# Final location is output / TRANSLATION[lang] / INDEX_PATH / index-*.html +INDEX_PATH = "" +# Final locations for the archives are: +# output / TRANSLATION[lang] / ARCHIVE_PATH / ARCHIVE_FILENAME +# output / TRANSLATION[lang] / ARCHIVE_PATH / YEAR / index.html +ARCHIVE_PATH = "" +ARCHIVE_FILENAME = "archive.html" +# Final locations are: +# output / TRANSLATION[lang] / RSS_PATH / rss.xml +RSS_PATH = "" + +# Slug the Tag URL easier for users to type, special characters are +# often removed or replaced as well. +SLUG_TAG_PATH = True + +# 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 = [] + +# Commands to execute to deploy. Can be anything, for example, +# you may use rsync: +# "rsync -rav output/* joe@my.site:/srv/www/site" +# And then do a backup, or ping pingomatic. +# To do manual deployment, set it to [] +DEPLOY_COMMANDS = [] + +# Where the output site should be located +# If you don't use an absolute path, it will be considered as relative +# to the location of conf.py + +OUTPUT_FOLDER = 'output' + +# Filters to apply to the output. +# A directory where the keys are either: a file extensions, or +# a tuple of file extensions. +# +# And the value is a list of commands to be applied in order. +# +# Each command must be either: +# +# A string containing a '%s' which will +# be replaced with a filename. The command *must* produce output +# in place. +# +# Or: +# +# A python callable, which will be called with the filename as +# argument. +# +# By default, there are no filters. +FILTERS = { +# ".jpg": ["jpegoptim --strip-all -m75 -v %s"], +} + +############################################################################## +# Image Gallery Options +############################################################################## + +# Galleries are folders in galleries/ +# Final location of galleries will be output / GALLERY_PATH / gallery_name +GALLERY_PATH = "galleries" +THUMBNAIL_SIZE = 180 +MAX_IMAGE_SIZE = 1280 +USE_FILENAME_AS_TITLE = True + +############################################################################## +# HTML fragments and diverse things that are used by the templates +############################################################################## + +# Data about post-per-page indexes +INDEXES_TITLE = "" # If this is empty, the default is BLOG_TITLE +INDEXES_PAGES = "" # If this is empty, the default is 'old posts page %d' translated + +# Name of the theme to use. Themes are located in themes/theme_name +THEME = 'site' + +# Show only teasers in the index pages? Defaults to False. +# INDEX_TEASERS = False + +# A HTML fragment describing the license, for the sidebar. +# I recomment using the Creative Commons' wizard: +# http://creativecommons.org/choose/ +LICENSE = """ +<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/2.5/ar/"> +<img alt="Creative Commons License BY-NC-SA" +style="border-width:0; margin-bottom:12px;" +src="http://i.creativecommons.org/l/by-nc-sa/2.5/ar/88x31.png"></a>""" + +# A small copyright notice for the page footer (in HTML) +CONTENT_FOOTER = u'Contents © 2012 Example Joe' + +# To enable comments via Disqus, you need to create a forum at +# http://disqus.com, and set DISQUS_FORUM to the short name you selected. +# If you want to disable comments, set it to False. +DISQUS_FORUM = "nikolademo" + +# Enable Addthis social buttons? +# Defaults to true +# ADD_THIS_BUTTONS = True + +# Modify the number of Post per Index Page +# Defaults to 10 +# INDEX_DISPLAY_POST_COUNT = 10 + +# RSS_LINK is a HTML fragment to link the RSS or Atom feeds. If set to None, +# the base.tmpl will use the feed Nikola generates. However, you may want to +# change it for a feedburner feed or something else. +RSS_LINK = None + +# A search form to search this site, for the sidebar. You can use a google +# custom search (http://www.google.com/cse/) +# Or a duckduckgo search: https://duckduckgo.com/search_box.html +# This example should work for pretty much any site we generate. +SEARCH_FORM = "" +# This search form is better for the "site" theme where it +# appears on the navigation bar +#SEARCH_FORM = """ +#<!-- Custom search --> +#<form method="get" id="search" action="http://duckduckgo.com/" """\ +#"""class="navbar-form pull-left"> +#<input type="hidden" name="sites" value="%s"/> +#<input type="hidden" name="k8" value="#444444"/> +#<input type="hidden" name="k9" value="#D51920"/> +#<input type="hidden" name="kt" value="h"/> +#<input type="text" name="q" maxlength="255" """\ +#"""placeholder="Search…" class="span2" style="margin-top: 4px;"/> +#<input type="submit" value="DuckDuckGo Search" style="visibility: hidden;" /> +#</form> +#<!-- End of custom search --> +#""" % BLOG_URL + +# Google analytics or whatever else you use. Added to the bottom of <body> +# in the default template (base.tmpl). +ANALYTICS = """ + """ + +# Put in global_context things you want available on all your templates. +# It can be anything, data, functions, modules, etc. +GLOBAL_CONTEXT = { + 'analytics': ANALYTICS, + 'blog_author': BLOG_AUTHOR, + 'blog_title': BLOG_TITLE, + 'blog_url': BLOG_URL, + 'blog_desc': BLOG_DESCRIPTION, + 'translations': TRANSLATIONS, + 'license': LICENSE, + 'search_form': SEARCH_FORM, + 'disqus_forum': DISQUS_FORUM, + 'content_footer': CONTENT_FOOTER, + 'rss_path': RSS_PATH, + 'rss_link': RSS_LINK, + # Locale-dependent links for the sidebar + # You should provide a key-value pair for each used language. + 'sidebar_links': { + DEFAULT_LANG: ( + ('/' + os.path.join(ARCHIVE_PATH, ARCHIVE_FILENAME), 'Archives'), + ('/categories/index.html', 'Tags'), + ('/stories/about-nikola.html', 'About Nikola'), + ('/stories/handbook.html', 'The Nikola Handbook'), + ('http://nikola.ralsina.com.ar', 'Powered by Nikola!'), + ), + } + } diff --git a/nikola/data/samplesite/conf.py.in b/nikola/data/samplesite/conf.py.in new file mode 100755 index 0000000..8794565 --- /dev/null +++ b/nikola/data/samplesite/conf.py.in @@ -0,0 +1,268 @@ +# -*- coding: utf-8 -*- + +import os + +######################################## +# Configuration, please edit +######################################## + +# Data about this site +BLOG_AUTHOR = "${BLOG_AUTHOR}" +BLOG_TITLE = "${BLOG_TITLE}" +BLOG_URL = "${BLOG_URL}" +BLOG_EMAIL = "${BLOG_EMAIL}" +BLOG_DESCRIPTION = "${BLOG_DESCRIPTION}" + + +# post_pages contains (wildcard, destination, template, use_in_feed) tuples. +# +# The wildcard is used to generate a list of reSt source files +# (whatever/thing.txt). +# That fragment must have an associated metadata file (whatever/thing.meta), +# and opcionally translated files (example for spanish, with code "es"): +# whatever/thing.txt.es and whatever/thing.meta.es +# +# 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 combinated with the template to produce rendered +# pages, which will be placed at +# output / TRANSLATIONS[lang] / destination / pagename.html +# +# where "pagename" is specified in the metadata file. +# +# if use_in_feed is True, then those posts will be added to the site's +# rss feeds. +# + +post_pages = ${POST_PAGES} + +# One or more folders containing files to be copied as-is into the output. +# The format is a dictionary of "source" "relative destination". +# Default is: +# FILES_FOLDERS = {'files': '' } +# Which means copy 'files' into 'output' + +# A mapping of languages to file-extensions that represent that language. +# Feel free to add or delete extensions to any list, but don't add any new +# compilers unless you write the interface for it yourself. +# +# 'rest' is reStructuredTextq +# 'markdown' is MarkDown +# 'html' assumes the file is html and just copies it +post_compilers = ${POST_COMPILERS} + +# Nikola is multilingual! +# +# Currently supported languages are: +# English -> en +# Greek -> gr +# German -> de +# French -> fr +# Russian -> ru +# Spanish -> es +# Italian -> it +# +# If you want to use Nikola with a non-supported language you have to provide +# a module containing the necessary translations +# (p.e. look at the modules at: ./nikola/data/themes/default/messages/fr.py). +# If a specific post is not translated to a language, then the version +# in the default language will be shown instead. + +# What is the default language? +DEFAULT_LANG = "${DEFAULT_LANG}" + +# What other languages do you have? +# The format is {"translationcode" : "path/to/translation" } +# the path will be used as a prefix for the generated pages location +TRANSLATIONS = { + "${DEFAULT_LANG}": "", + #"gr": "./gr", + #"de": "./de", + #"fr": "./fr", + #"ru": "./ru", + #"es": "./es", + } + +# Paths for different autogenerated bits. These are combined with the +# translation paths. + +# Final locations are: +# output / TRANSLATION[lang] / TAG_PATH / index.html (list of tags) +# output / TRANSLATION[lang] / TAG_PATH / tag.html (list of posts for a tag) +# output / TRANSLATION[lang] / TAG_PATH / tag.xml (RSS feed for a tag) +TAG_PATH = "categories" + +# If TAG_PAGES_ARE_INDEXES is set to True, each tag's page will contain +# the posts themselves. If set to False, it will be just a list of links. +TAG_PAGES_ARE_INDEXES = True + +# Final location is output / TRANSLATION[lang] / INDEX_PATH / index-*.html +INDEX_PATH = "" +# Final locations for the archives are: +# output / TRANSLATION[lang] / ARCHIVE_PATH / ARCHIVE_FILENAME +# output / TRANSLATION[lang] / ARCHIVE_PATH / YEAR / index.html +ARCHIVE_PATH = "" +ARCHIVE_FILENAME = "archive.html" +# Final locations are: +# output / TRANSLATION[lang] / RSS_PATH / rss.xml +RSS_PATH = "" + +# Slug the Tag URL easier for users to type, special characters are +# often removed or replaced as well. +SLUG_TAG_PATH = True + +# 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 = [] + +# Commands to execute to deploy. Can be anything, for example, +# you may use rsync: +# "rsync -rav output/* joe@my.site:/srv/www/site" +# And then do a backup, or ping pingomatic. +# To do manual deployment, set it to [] +DEPLOY_COMMANDS = [] + +# Where the output site should be located +# If you don't use an absolute path, it will be considered as relative +# to the location of conf.py + +OUTPUT_FOLDER = 'output' + +# Filters to apply to the output. +# A directory where the keys are either: a file extensions, or +# a tuple of file extensions. +# +# And the value is a list of commands to be applied in order. +# +# Each command must be either: +# +# A string containing a '%s' which will +# be replaced with a filename. The command *must* produce output +# in place. +# +# Or: +# +# A python callable, which will be called with the filename as +# argument. +# +# By default, there are no filters. +FILTERS = { +# ".jpg": ["jpegoptim --strip-all -m75 -v %s"], +} + +############################################################################## +# Image Gallery Options +############################################################################## + +# Galleries are folders in galleries/ +# Final location of galleries will be output / GALLERY_PATH / gallery_name +GALLERY_PATH = "galleries" +THUMBNAIL_SIZE = 180 +MAX_IMAGE_SIZE = 1280 +USE_FILENAME_AS_TITLE = True + +############################################################################## +# HTML fragments and diverse things that are used by the templates +############################################################################## + +# Data about post-per-page indexes +INDEXES_TITLE = "" # If this is empty, the default is BLOG_TITLE +INDEXES_PAGES = "" # If this is empty, the default is 'old posts page %d' translated + +# Name of the theme to use. Themes are located in themes/theme_name +THEME = 'site' + +# Show only teasers in the index pages? Defaults to False. +# INDEX_TEASERS = False + +# A HTML fragment describing the license, for the sidebar. +# I recomment using the Creative Commons' wizard: +# http://creativecommons.org/choose/ +LICENSE = """ +<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/2.5/ar/"> +<img alt="Creative Commons License BY-NC-SA" +style="border-width:0; margin-bottom:12px;" +src="http://i.creativecommons.org/l/by-nc-sa/2.5/ar/88x31.png"></a>""" + +# A small copyright notice for the page footer (in HTML) +CONTENT_FOOTER = u'Contents © 2012 <a href="${BLOG_EMAIL}">${BLOG_AUTHOR}</a>' + +# To enable comments via Disqus, you need to create a forum at +# http://disqus.com, and set DISQUS_FORUM to the short name you selected. +# If you want to disable comments, set it to False. +DISQUS_FORUM = "nikolademo" + +# Enable Addthis social buttons? +# Defaults to true +# ADD_THIS_BUTTONS = True + +# Modify the number of Post per Index Page +# Defaults to 10 +# INDEX_DISPLAY_POST_COUNT = 10 + +# RSS_LINK is a HTML fragment to link the RSS or Atom feeds. If set to None, +# the base.tmpl will use the feed Nikola generates. However, you may want to +# change it for a feedburner feed or something else. +RSS_LINK = None + +# A search form to search this site, for the sidebar. You can use a google +# custom search (http://www.google.com/cse/) +# Or a duckduckgo search: https://duckduckgo.com/search_box.html +# This example should work for pretty much any site we generate. +SEARCH_FORM = "" +# This search form is better for the "site" theme where it +# appears on the navigation bar +#SEARCH_FORM = """ +#<!-- Custom search --> +#<form method="get" id="search" action="http://duckduckgo.com/" """\ +#"""class="navbar-form pull-left"> +#<input type="hidden" name="sites" value="%s"/> +#<input type="hidden" name="k8" value="#444444"/> +#<input type="hidden" name="k9" value="#D51920"/> +#<input type="hidden" name="kt" value="h"/> +#<input type="text" name="q" maxlength="255" """\ +#"""placeholder="Search…" class="span2" style="margin-top: 4px;"/> +#<input type="submit" value="DuckDuckGo Search" style="visibility: hidden;" /> +#</form> +#<!-- End of custom search --> +#""" % BLOG_URL + +# Google analytics or whatever else you use. Added to the bottom of <body> +# in the default template (base.tmpl). +ANALYTICS = """ + """ + +# Put in global_context things you want available on all your templates. +# It can be anything, data, functions, modules, etc. +GLOBAL_CONTEXT = { + 'analytics': ANALYTICS, + 'blog_author': BLOG_AUTHOR, + 'blog_title': BLOG_TITLE, + 'blog_url': BLOG_URL, + 'blog_desc': BLOG_DESCRIPTION, + 'translations': TRANSLATIONS, + 'license': LICENSE, + 'search_form': SEARCH_FORM, + 'disqus_forum': DISQUS_FORUM, + 'content_footer': CONTENT_FOOTER, + 'rss_path': RSS_PATH, + 'rss_link': RSS_LINK, + # Locale-dependent links for the sidebar + # You should provide a key-value pair for each used language. + 'sidebar_links': { + DEFAULT_LANG: ( + ('/' + os.path.join(ARCHIVE_PATH, ARCHIVE_FILENAME), 'Archives'), + ('/categories/index.html', 'Tags'), + ('/stories/about-nikola.html', 'About Nikola'), + ('/stories/handbook.html', 'The Nikola Handbook'), + ('http://nikola.ralsina.com.ar', 'Powered by Nikola!'), + ), + } + } diff --git a/nikola/data/samplesite/dodo.py b/nikola/data/samplesite/dodo.py new file mode 100755 index 0000000..1be7663 --- /dev/null +++ b/nikola/data/samplesite/dodo.py @@ -0,0 +1,21 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- + +# Please don't edit this file unless you really know what you are doing. +# The configuration is now in conf.py + +from doit.reporter import ExecutedOnlyReporter + +from nikola.nikola import Nikola + +import conf + +DOIT_CONFIG = { + 'reporter': ExecutedOnlyReporter, + 'default_tasks': ['render_site'], +} +SITE = Nikola(**conf.__dict__) + + +def task_render_site(): + return SITE.gen_tasks() diff --git a/nikola/data/samplesite/files/assets/css/custom.css b/nikola/data/samplesite/files/assets/css/custom.css new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/nikola/data/samplesite/files/assets/css/custom.css diff --git a/nikola/data/samplesite/files/favicon.ico b/nikola/data/samplesite/files/favicon.ico Binary files differnew file mode 100644 index 0000000..c4efbcc --- /dev/null +++ b/nikola/data/samplesite/files/favicon.ico diff --git a/nikola/data/samplesite/galleries/demo/exclude.meta b/nikola/data/samplesite/galleries/demo/exclude.meta new file mode 100644 index 0000000..967e566 --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/exclude.meta @@ -0,0 +1 @@ +tesla2_lg.jpg diff --git a/nikola/data/samplesite/galleries/demo/index.txt b/nikola/data/samplesite/galleries/demo/index.txt new file mode 100644 index 0000000..d3d5a44 --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/index.txt @@ -0,0 +1,2 @@ +Some public domain pictures of Nikola Tesla +(copied from `here <http://kerryr.net/pioneers/gallery/tesla.htm>`_)
\ No newline at end of file diff --git a/nikola/data/samplesite/galleries/demo/tesla2_lg.jpg b/nikola/data/samplesite/galleries/demo/tesla2_lg.jpg Binary files differnew file mode 100644 index 0000000..8be0531 --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/tesla2_lg.jpg diff --git a/nikola/data/samplesite/galleries/demo/tesla4_lg.jpg b/nikola/data/samplesite/galleries/demo/tesla4_lg.jpg Binary files differnew file mode 100644 index 0000000..e350491 --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/tesla4_lg.jpg diff --git a/nikola/data/samplesite/galleries/demo/tesla_conducts_lg.jpg b/nikola/data/samplesite/galleries/demo/tesla_conducts_lg.jpg Binary files differnew file mode 100644 index 0000000..7549d09 --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/tesla_conducts_lg.jpg diff --git a/nikola/data/samplesite/galleries/demo/tesla_lightning1_lg.jpg b/nikola/data/samplesite/galleries/demo/tesla_lightning1_lg.jpg Binary files differnew file mode 100644 index 0000000..7e4a6a0 --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/tesla_lightning1_lg.jpg diff --git a/nikola/data/samplesite/galleries/demo/tesla_lightning2_lg.jpg b/nikola/data/samplesite/galleries/demo/tesla_lightning2_lg.jpg Binary files differnew file mode 100644 index 0000000..730b4de --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/tesla_lightning2_lg.jpg diff --git a/nikola/data/samplesite/galleries/demo/tesla_tower1_lg.jpg b/nikola/data/samplesite/galleries/demo/tesla_tower1_lg.jpg Binary files differnew file mode 100644 index 0000000..1b9edcb --- /dev/null +++ b/nikola/data/samplesite/galleries/demo/tesla_tower1_lg.jpg diff --git a/nikola/data/samplesite/listings/hello.py b/nikola/data/samplesite/listings/hello.py new file mode 100644 index 0000000..695c212 --- /dev/null +++ b/nikola/data/samplesite/listings/hello.py @@ -0,0 +1,10 @@ +#!/usr/bin/python + +import sys + + +def hello(name='world'): + print "hello", name + +if __name__ == "__main__": + hello(*sys.argv[1:]) diff --git a/nikola/data/samplesite/posts/1.meta b/nikola/data/samplesite/posts/1.meta new file mode 100644 index 0000000..3bc104a --- /dev/null +++ b/nikola/data/samplesite/posts/1.meta @@ -0,0 +1,5 @@ +Welcome to Nikola +welcome-to-nikola +2012/03/30 23:00 +nikola, python, demo, blog +http://nikola.ralsina.com.ar diff --git a/nikola/data/samplesite/posts/1.txt b/nikola/data/samplesite/posts/1.txt new file mode 100644 index 0000000..4e583db --- /dev/null +++ b/nikola/data/samplesite/posts/1.txt @@ -0,0 +1,13 @@ +.. figure:: http://farm1.staticflickr.com/138/352972944_4f9d568680.jpg + :target: http://farm1.staticflickr.com/138/352972944_4f9d568680_z.jpg?zz=1 + :class: thumbnail + :alt: Nikola Tesla Corner by nicwest, on Flickr + +If you can see this in a web browser, it means you have managed to install Nikola, +and build a site using it. Congratulations! + +* You can read the manual `here </stories/handbook.html>`__ +* You can learn more about Nikola at http://nikola.ralsina.com.ar +* You can see a demo photo gallery `here </galleries/demo/>`__ + +Send feedback to ralsina@netmanagers.com.ar! diff --git a/nikola/data/samplesite/stories/1.meta b/nikola/data/samplesite/stories/1.meta new file mode 100644 index 0000000..e19bf10 --- /dev/null +++ b/nikola/data/samplesite/stories/1.meta @@ -0,0 +1,4 @@ +Nikola: it generates static +about-nikola +2012/03/30 23:00 + diff --git a/nikola/data/samplesite/stories/1.txt b/nikola/data/samplesite/stories/1.txt new file mode 100644 index 0000000..68b4008 --- /dev/null +++ b/nikola/data/samplesite/stories/1.txt @@ -0,0 +1,4 @@ +Hope you enjoy this software! + +* Home page at http://nikola.ralsina.com.ar +* Author's blog (and reason why Nikola exists): http://lateral.netmanagers.com.ar diff --git a/nikola/data/samplesite/stories/configsample.meta b/nikola/data/samplesite/stories/configsample.meta new file mode 100644 index 0000000..530d05f --- /dev/null +++ b/nikola/data/samplesite/stories/configsample.meta @@ -0,0 +1,4 @@ +Sample Nikola Config File +sampleconfig +2012/03/30 23:00 + diff --git a/nikola/data/samplesite/stories/configsample.txt b/nikola/data/samplesite/stories/configsample.txt new file mode 100755 index 0000000..89d296e --- /dev/null +++ b/nikola/data/samplesite/stories/configsample.txt @@ -0,0 +1,221 @@ +.. code-block:: python + + #!/usr/bin/env python + # -*- coding: utf-8 -*- + + ######################################## + # Configuration, please edit + ######################################## + + # post_pages contains (wildcard, destination, template, use_in_feed) tuples. + # + # The wildcard is used to generate a list of reSt source files (whatever/thing.txt) + # That fragment must have an associated metadata file (whatever/thing.meta), + # and opcionally translated files (example for spanish, with code "es"): + # whatever/thing.txt.es and whatever/thing.meta.es + # + # From those files, a set of HTML fragment files will be generated: + # whatever/thing.html (and maybe whatever/thing.html.es) + # + # These files are combinated with the template to produce rendered + # pages, which will be placed at + # output / TRANSLATIONS[lang] / destination / pagename.html + # + # where "pagename" is specified in the metadata file. + # + # if use_in_feed is True, then those posts will be added to the site's + # rss feeds. + # + + post_pages = ( + ("posts/*.txt", "weblog/posts", "post.tmpl", True), + ("stories/*.txt", "stories", "post.tmpl", False), + ) + + # What is the default language? + + DEFAULT_LANG = "en" + + # What languages do you have? + # If a specific post is not translated to a language, then the version + # in the default language will be shown instead. + # The format is {"translationcode" : "path/to/translation" } + # the path will be used as a prefix for the generated pages location + + TRANSLATIONS = { + "en": "", + "es": "tr/es", + } + + # Paths for different autogenerated bits. These are combined with the translation + # paths. + + # Final locations are: + # output / TRANSLATION[lang] / TAG_PATH / index.html (list of tags) + # output / TRANSLATION[lang] / TAG_PATH / tag.html (list of posts for a tag) + # output / TRANSLATION[lang] / TAG_PATH / tag.xml (RSS feed for a tag) + TAG_PATH = "categories" + # Final location is output / TRANSLATION[lang] / INDEX_PATH / index-*.html + INDEX_PATH = "weblog" + # Final locations for the archives are: + # output / TRANSLATION[lang] / ARCHIVE_PATH / archive.html + # output / TRANSLATION[lang] / ARCHIVE_PATH / YEAR / index.html + ARCHIVE_PATH = "weblog" + # Final locations are: + # output / TRANSLATION[lang] / RSS_PATH / rss.xml + RSS_PATH = "weblog" + + # 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")] + + # Commands to execute to deploy. Can be anything, for example, + # you may use rsync: + # "rsync -rav output/* joe@my.site:/srv/www/site" + # And then do a backup, or ping pingomatic. + # To do manual deployment, set it to [] + DEPLOY_COMMANDS = [ + r'rsync -rav --delete output/* ralsina@lateral.netmanagers.com.ar:/srv/www/lateral', + r'rdiff-backup output ~/bartleblog-backup', + r"links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar' > /dev/null", + r"links -dump 'http://pingomatic.com/ping/?title=Lateral+Opinion&blogurl=http%%3A%%2F%%2Flateral.netmanagers.com.ar&rssurl=http%%3A%%2F%%2F&chk_weblogscom=on&chk_blogs=on&chk_technorati=on&chk_feedburner=on&chk_syndic8=on&chk_newsgator=on&chk_myyahoo=on&chk_pubsubcom=on&chk_blogdigger=on&chk_blogrolling=on&chk_blogstreet=on&chk_moreover=on&chk_weblogalot=on&chk_icerocket=on&chk_newsisfree=on&chk_topicexchange=on&chk_google=on&chk_tailrank=on&chk_bloglines=on&chk_aiderss=on&chk_skygrid=on&chk_bitacoras=on&chk_collecta=on' > /dev/null", + r'rsync -rav ~/bartleblog-backup/* ralsina@netmanagers.com.ar:bartleblog-backup', + ] + + ############################################################################## + # Image Gallery Options + ############################################################################## + + # Galleries are folders in galleries/ + # Final location of galleries will be output / GALLERY_PATH / gallery_name + GALLERY_PATH = "galleries" + THUMBNAIL_SIZE = 256 + + + ############################################################################## + # HTML fragments and diverse things that are used by the templates + ############################################################################## + + # Data about this site + BLOG_TITLE = "Lateral Opinion" + BLOG_URL = "http://lateral.netmanagers.com.ar" + BLOG_EMAIL = "ralsina@kde.org" + BLOG_DESCRIPTION = "I write free software. I have an opinion on almost "\ + "everything. I write quickly. A weblog was inevitable." + + # A HTML fragment describing the license, for the sidebar. + # I recomment using Creative Commons' wizard: http://creativecommons.org/choose/ + LICENSE = """ + <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/2.5/ar/"> + <img alt="Creative Commons License" style="border-width:0; margin-bottom:12px;" + src="http://i.creativecommons.org/l/by-nc-sa/2.5/ar/88x31.png"></a>""" + + # A small copyright notice for the page footer + CONTENT_FOOTER = u"Contents © 2000-2012 Roberto Alsina <ralsina@kde.org>" + + # To enable comments via Disqus, you need to create a forum at http://disqus.com, + # and set DISQUS_FORUM to the short name you selected. + # If you want to disable comments, set it to False. + DISQUS_FORUM = "lateralopinion" + + # RSS_LINK is a HTML fragment to link the RSS or Atom feeds. If set to None, + # the base.tmpl will use the feed Nikola generates. However, you may want to + # change it for a feedburner feed or something else. + + #RSS_LINK = """ + #<link rel="alternate" type="application/rss+xml" title="RSS" href="http://feeds.feedburner.com/LateralOpinion"> + #<link rel="alternate" type="application/rss+xml" title="RSS en Espanol" href="http://feeds.feedburner.com/LateralOpinionEsp"> + #""" + RSS_LINK = None + + # A search form to search this site, for the sidebar. You can use a google + # custom search (http://www.google.com/cse/) + # Or a duckduckgo search: https://duckduckgo.com/search_box.html + # This example should work for pretty much any site we generate. + SEARCH_FORM = """ + <!-- Custom search --> + <form method="get" id="search" action="http://duckduckgo.com/"> + <input type="hidden" name="sites" value="%s"/> + <input type="hidden" name="k8" value="#444444"/> + <input type="hidden" name="k9" value="#D51920"/> + <input type="hidden" name="kt" value="h"/> + <input type="text" name="q" maxlength="255" placeholder="Search…" class="span2" style="margin-top: 4px;"/> + <input type="submit" value="DuckDuckGo Search" style="visibility: hidden;" /> + </form> + <!-- End of custom search --> + """ % BLOG_URL + + # Google analytics or whatever else you use. Added to the bottom of <body> + # in the default template (base.tmpl). + ANALYTICS = """ + <!-- Start of StatCounter Code --> + <script type="text/javascript"> + sc_project=1436219; + sc_invisible=1; + sc_partition=13; + sc_security="b91cd70a"; + </script> + <script type="text/javascript" src="http://www.statcounter.com/counter/counter.js"></script> + <noscript> + <div class="statcounter"> + <a title="free hit counters" href="http://www.statcounter.com/" target="_blank"><img class="statcounter" src="http://c14.statcounter.com/1436219/0/b91cd70a/1/" alt="free hit counters" ></a> + </div> + </noscript> + <!-- End of StatCounter Code --> + <!-- Start of Google Analytics --> + <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> + </script> + <script type="text/javascript"> + _uacct = "UA-1639287-1"; + urchinTracker(); + </script> + <!-- End of Google Analytics --> + """ + + # Put in global_context things you want available on all your templates. + # It can be anything, data, functions, modules, etc. + GLOBAL_CONTEXT = { + 'analytics': ANALYTICS, + 'blog_title': BLOG_TITLE, + 'blog_url': BLOG_URL, + 'translations': TRANSLATIONS, + 'license': LICENSE, + 'search_form': SEARCH_FORM, + 'disqus_forum': DISQUS_FORUM, + 'content_footer': CONTENT_FOOTER, + 'rss_path': RSS_PATH, + 'rss_link': RSS_LINK, + # Locale-dependent links for the sidebar + 'sidebar_links': { + 'en': ( + ('/archive.html', 'Archives'), + ('/categories/index.html', 'Tags'), + ('http://nikola.ralsina.com.ar', 'Powered by Nikola!'), + ), + 'es': ( + ('/archive.html', 'Archivos'), + ('/categories/index.html', 'Tags'), + ('http://nikola.ralsina.com.ar', 'Powered by Nikola!'), + ) + } + } + + # Sorry, this is magic. It just is. + execfile("nikola/nikola.py") + if __name__ == "__main__": + nikola_main() + # End of magic. + + # To disable tasks, just delete them. For example, if you really + # do not want to do a sitemap: + # del(task_sitemap) + + # You can also replace the provided tasks with your own by redefining them + # below this point. For a list of current tasks, run "doit list", and for + # help on their syntax, refer to the doit handbook at http://python-doit.sf.net diff --git a/nikola/data/samplesite/stories/manual.meta b/nikola/data/samplesite/stories/manual.meta new file mode 100644 index 0000000..b5e43ec --- /dev/null +++ b/nikola/data/samplesite/stories/manual.meta @@ -0,0 +1,4 @@ +The Nikola Handbook +handbook +2012/03/30 23:00 + diff --git a/nikola/data/samplesite/stories/manual.txt b/nikola/data/samplesite/stories/manual.txt new file mode 100644 index 0000000..f8804e6 --- /dev/null +++ b/nikola/data/samplesite/stories/manual.txt @@ -0,0 +1,808 @@ +The Nikola Handbook +=================== + +:Version: 2.1+svn +:Author: Roberto Alsina <ralsina@netmanagers.com.ar> + +.. class:: alert alert-info pull-right + +.. contents:: + + +All You Need to Know +-------------------- + +After you have Nikola installed: + +Create a site: + ``nikola init mysite`` + +Create a post: + ``doit new_post`` + +Edit the post: + The filename should be in the output of the previous command. + +Build the site: + ``doit`` + +Start the test server: + ``doit serve`` + +See the site: + http://127.0.0.1:8000 + +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. + +It's 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://lateral.netmanagers.com.ar>`__) +* Your company's site +* Your personal site +* A software project's site (`example <http://nikola.ralsina.com.ar>`__) +* 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_!) + +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 +------------ + +* Feel free to contact me at ralsina@netmanagers.com.ar for questions about Nikola. +* You can file bugs at `the issue tracker <http://code.google.com/p/nikola-generator/issues/list>`__ +* You can discuss Nikola at the `nikola-discuss google group <http://groups.google.com/group/nikola-discuss>`_ +* You can subscribe to `the Nikola Blog <http://nikola.ralsina.com.ar/blog>`_ +* You can follow `Nikola on Twitter <https://twitter.com/#!/nikolagenerator>`_ + +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 webserver). + + A smaller software stack implies less security risk. + +Obsolescense + 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.5 (soon 3.x) in a Linux, Windows, or Mac 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. + +Lockin + 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 homebrewed 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. + +Features +-------- + +Nikola has a very defined featureset: it has every feature I needed for my own sites. +Hopefully, it will be enough for others, and anyway, I am open to suggestions. + +If you want to create a blog or a site, Nikola provides: + +* Front page (and older posts pages) +* RSS Feeds +* Pages and feeds for each tag you used +* Custom search +* Full yearly archives +* Custom output paths for generated pages +* Easy page template customization +* Static pages (not part of the blog) +* Internationalization support (my own blog is English/Spanish) +* Google sitemap generation +* Custom deployment (if it's a command, you can use it) +* A (very) basic look and feel you can customize, and is even text-mode friendly +* The input format is light markup (`reStructuredText <quickstart.html>`_ or + `Markdown <http://daringfireball.net/projects/markdown/>`_) +* Easy-to-create image galleries + +Also: + +* A preview webserver +* "Live" re-rendering while you edit +* "Smart" builds: only what changed gets rebuilt (usually in 1 or 2 seconds) +* Very easy to extend with minimal Python knowledge. + +Installing Nikola +----------------- + +This is currently lacking on detail. Considering the niche Nikola is aimed at, +I suspect that's not a problem yet. So, when I say "get", the specific details +of how to "get" something for your specific operating system are left to you. + +The short version is: ``pip install https://github.com/ralsina/nikola/zipball/master`` + +Longer version: + +#. Get python, if you don't have it. +#. Get `doit <http://python-doit.sf.net>`_ +#. Get `docutils <http://docutils.sf.net>`_ +#. Get `Mako <http://makotemplates.org>`_ +#. Get `PIL <http://www.pythonware.com/products/pil/>`_ +#. Get `Pygments <http://pygments.org/>`_ +#. Get `unidecode <http://pypi.python.org/pypi/Unidecode/>`_ +#. Get `lxml <http://lxml.de/>`_ + +Any non-prehistorical version of the above should work, and if you are in Linux +you can try to use your distribution's packages if they exist, but the newer the better. + +Then get Nikola itself (<http://nikola.ralsina.com.ar/>), unzip it, and +run ``python setup.py install``. + +After that, run ``nikola init sitename`` and that will create a folder called +``sitename`` containing a functional demo site. + +Getting Started +--------------- + +To create posts and pages in Nikola, you write them in restructured text or Markdown, light +markups that are later converted to HTML (I may add support for textile or other +markups later). There is a great `quick tutorial to learn restructured text. <quickstart.html>`_ + +First, let's see how you "build" your site. Nikola comes with a minimal site to get you started. + +The tool used to do builds is called `doit <http://python-doit.sf.net>`_, and it rebuilds the +files that are not up to date, so your site always reflects your latest content. To do our +first build, just run "doit":: + + $ doit + Parsing metadata + . render_posts:stories/manual.html + . render_posts:posts/1.html + . render_posts:stories/1.html + . render_archive:output/2012/index.html + . render_archive:output/archive.html + . render_indexes:output/index.html + . render_pages:output/posts/welcome-to-nikola.html + . render_pages:output/stories/about-nikola.html + . render_pages:output/stories/handbook.html + . render_rss:output/rss.xml + . render_sources:output/stories/about-nikola.txt + : + : + : + +Nikola will print a line for every output file it generates. If we do it again, that +will be much much shorter:: + + $ doit + Parsing metadata + . sitemap + +That is because `doit <http://python-doit.sf.net>`_ is smart enough not to generate +all the pages again, unless you changed something that the page requires. So, if you change +the text of a post, or its title, that post page, and all index pages where it is mentioned, +will be recreated. If you change the post page template, then all the post pages will be rebuilt. + +Nikola is a series of doit *tasks*, and you can see them by doing ``doit list``:: + + $ doit list + Scanning posts . . done! + copy_assets Create tasks to copy the assets of the whole theme chain. + copy_files Copy static files into the output folder. + deploy Deploy site. + new_page Create a new post (interactive). + new_post Create a new post (interactive). + redirect Generate redirections. + render_archive Render the post archives. + render_galleries Render image galleries. + render_indexes Render 10-post-per-page indexes. + render_pages Build final pages from metadata and HTML fragments. + render_posts Build HTML fragments from metadata and reSt. + render_rss Generate RSS feeds. + render_site Render the post archives. + render_sources Publish the rst sources because why not? + render_tags Render the tag pages. + serve Start test server. (Usage: doit serve [--address 127.0.0.1] [--port 8000]) + sitemap Generate Google sitemap. + +You can make Nikola redo everything by calling ``doit clean``, you can make it do just a specific +part of the site using task names, for example ``doit render_pages``, and even individual files like +``doit render_indexes:output/index.html`` + +The ``serve`` task is special, in that instead of generating a file it starts a web server so +you can see the site you are creating:: + + $ doit serve + Parsing metadata + . serve + Serving HTTP on 127.0.0.1 port 8000 ... + +After you do this, you can point your web browser to http://localhost:8000 and you should see +the sample site. This is useful as a "preview" of your work. You can combine add ``auto`` and do +``doit auto serve`` which makes doit automatically regenerate your pages as needed, and +it's a live preview! + +By default, the ``serve`` task runs the web server on port 8000 on the IP address 127.0.0.1. +You can pass in an IP address and port number explicity using ``-a IP_ADDRESS`` +(short version of ``--address``) or ``-p PORT_NUMBER`` (short version of ``--port``) +Example usage:: + + $ doit serve --address 0.0.0.0 --port 8080 + Parsing metadata + . serve + Serving HTTP on 0.0.0.0 port 8080 ... + +The ``deploy`` task is discussed in the Deployment_ section. + +Creating a Blog Post +-------------------- + +A post consists of two files, a metadata file (``post-title.meta``) and a +file containing the contents written in `restructured text <http://docutils.sf.net>`_ +(``post-title.txt``), markdown or HTML. Which input type is used is guessed using +the ``post_compilers`` option in ``conf.py`` but by default, the extensions +supported are: + +.txt .rst + Restructured Text + +.md .markdown .mdown + Markdown + +.htm .html + HTML + +The default configuration expects them to be placed in ``posts`` but that can be +changed (see below, the post_pages option) + +You can just create them in ``posts`` or use a little helper task provided by Nikola:: + + $ doit new_post + Parsing metadata + . new_post + Creating New Post + ----------------- + + Enter title: How to Make Money + Your post's metadata is at: posts/how-to-make-money.meta + Your post's text is at: posts/how-to-make-money.txt + +The format for the ``.meta`` file is as follows:: + + How to Make Money + how-to-make-money + 2012/04/09 13:59 + +The first line is the title. The second one is the pagename. 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". + +You can add three more optional lines. A fourth line that is a list of tags +separated with commas (spaces around the commas are ignored):: + + programming, python, fame, fortune + +And a fifth line that's a URL for an original source of the post. + +And a sixth line that's the page description. + +If you are writing a multilingual site, you can also create a per-language +metadata file. This one can have two lines: + +1) The translated title for the post or page +2) A translated version of the pagename + +You can edit these files with your favourite text editor, and once you are happy +with the contents, generate the pages as explained in `Getting Started`_ + +Currently supported languages are + +* English +* Spanish +* French +* German +* Russian +* Greek. + +If you wish to add support for more languages, check out the instructions +at the `theming guide <http://nikola.ralsina.com.ar/theming.html>`. + +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 ``post_pages`` +configuration option:: + + # post_pages contains (wildcard, destination, template, use_in_feed) tuples. + # + # The wildcard is used to generate a list of reSt source files (whatever/thing.txt) + # That fragment must have an associated metadata file (whatever/thing.meta), + # and opcionally translated files (example for spanish, with code "es"): + # whatever/thing.txt.es and whatever/thing.meta.es + # + # 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 combinated with the template to produce rendered + # pages, which will be placed at + # output / TRANSLATIONS[lang] / destination / pagename.html + # + # where "pagename" is specified in the metadata file. + # + # if use_in_feed is True, then those posts will be added to the site's + # rss feeds. + # + post_pages = ( + ("posts/*.txt", "posts", "post.tmpl", True), + ("stories/*.txt", "stories", "story.tmpl", False), + ) + +It will use the first location that has the last parameter set to True, or the last +one in the list if all of them have it set to False. + +Alternatively, you can not have a meta file and embed the metadata in the post itself. + +In restructured text:: + + .. tags: test,demo + .. slug: demo-test + .. date: 2012/04/09 13:59 + .. link: http://foo.bar/baz + +In Markdown: + <!-- + .. tags: test,demo + .. slug: demo-test + .. date: 2012/04/09 13:59 + .. link: http://foo.bar/baz + --> + +Teasers +~~~~~~~ + +If for any reason you want to provide feeds that only display the beginning of +your post, you only need to add a "magical comment" in your post. + +In restructuredtext:: + + .. TEASER_END + +In Markdown:: + + <!-- TEASER_END --> + +Additionally, if you want also the "index" pages to show only the teasers, you can +set the variable ``INDEX_TEASERS`` to ``True`` in ``conf.py``. + +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. + + +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 post_pages option above). + +You can create the page's files manually or use the helper ``new_page`` that works exactly like +the ``new_post`` described above, except it will place the files in the folder that +has ``use_in_feed`` set to False. + +Redirections +------------ + +If you need a page to be available in more than one place, you can define redirections +in your ``conf.py``:: + + # 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, but just in case, here is a full, +`customized example configuration <sampleconfig.html>`_ (the one I use for +`my site <http://lateral.netmanagers.com.ar>`_) + +Adding Files +------------ + +Any files you want to be in ``output/`` but are not generated by Nikola (for example, +``favicon.ico``, just put it in ``files/``. Everything there is copied into +``output`` by the ``copy_files`` task. Remember that you can't have files that collide +with files Nikola generates (it will give an error). + +.. admonition:: Important + + Don't put any files manually in ``output/``. Ever. Really. Maybe someday Nikola + will just wipe ``output/`` and then you will be sorry. So, please don't do that. + +If you want to copy more than one folder of static files into ``output`` you can +change the FILES_FOLDERS option:: + + # One or more folders containing files to be copied as-is into the output. + # The format is a dictionary of "source" "relative destination". + # Default is: + # FILES_FOLDERS = {'files': '' } + # Which means copy 'files' into 'output' + +Post Processing Filters +----------------------- + +You can apply post processing to the files in your site, in order to optimize them +or change them in arbitrary ways. For example, you may want to compress all CSS +and JS files using yui-compressor. + +To do that, you can use the provided helper adding this in your ``config.py``:: + + from nikola import filters + + FILTERS = { + ".css": [filters.yui_compressor], + ".js": [filters.yui_compressor], + } + +Where ``filters.yui_compressor`` is a helper function provided by Nikola. You can +replace that with strings describing command lines, or arbitrary python functions. + +If there's any specific thing you expect to be generally useful as a filter, contact +me and I will add it to the filters library so that more people use it. + +Customizing Your Site +--------------------- + +There are lots of things you can do to persoalize your website, but let's see the easy ones! + +Basics + You can assume this needs to be changed:: + + # Data about this site + BLOG_TITLE = "Demo Site" + BLOG_URL = "http://nikola.ralsina.com.ar" + BLOG_EMAIL = "joe@demo.site" + BLOG_DESCRIPTION = "This is a demo site for Nikola." + +CSS tweaking + The default configuration includes a file, ``themes/default/assets/css/custom.css`` + which is empty. Put your CSS 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>`_. + +Template tweaking + If you really want to change the pages radically, you will want to do a + `custom theme <theming.html>`_. + + +Sidebar + ``LICENSE`` is a HTML snippet for things like a CC badge, or whatever you prefer. + + The 'sidebar_links' option lets you define what links go in the right-hand + sidebar, so you can link to important pages, or to other sites. + + 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. + +Analytics + This is probably a misleading name, but the ``ANALYTICS`` 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. + +Getting More Themes +------------------- + +There are not so many themes for Nikola. On occasion, I port something I like, and make +it available for download. Nikola has a builtin theme download/install mechanism, its +``install_theme`` task:: + + $ doit install_theme -l + Scanning posts . . done! + . install_theme + Themes: + ------- + blogtxt + readable + + $ doit install_theme -n blogtxt + Scanning posts . . done! + . install_theme + Downloading: http://nikola.ralsina.com.ar/themes/blogtxt.zip + Extracting: blogtxt into themes + +And there you are, you now have themes/blogtxt installed. It's very rudimentary, but it +should work in most cases. + +If you create a nice theme, please share it! You can post about it on +`the nikola forum <http://groups.google.com/group/nikola-discuss>`_ and I will +make it available for download. + +One other option is to tweak an existing theme using a different color scheme, +typography and CSS in general. Nikola provides a ``bootswatch_theme`` option +to create a custom theme by downloading free CSS files from http://bootswatch.com:: + + $ doit bootswatch_theme -n custom_theme -s spruce -p site + Scanning posts . . done! + . bootswatch_theme + Creating custom_theme theme from spruce and site + Downloading: http://bootswatch.com/spruce/bootstrap.min.css + Downloading: http://bootswatch.com/spruce/bootstrap.css + Theme created. Change the THEME setting to "custom_theme" to use it. + +You can even try what different swatches do on an existing site using +their handy `bootswatchlet <http://news.bootswatch.com/post/29555952123/a-bookmarklet-for-bootswatch>`_ + +Play with it, there's cool stuff there. This feature was suggested by +`clodo <http://elgalpondebanquito.com.ar>`_. + +Deployment +---------- + +Nikola doesn't really have a concept of deployment. However, if you can specify your +deployment procedure as a series of commands, you can put them in the ``DEPLOY_COMMANDS`` +option, and run them with ``doit deploy``. + +One caveat is that if any command has a % in it, you should double them. + +Here is an example, from my own site's deployment script:: + + DEPLOY_COMMANDS = [ + 'rsync -rav --delete output/* ralsina@lateral.netmanagers.com.ar:/srv/www/lateral', + 'rdiff-backup output ~/bartleblog-backup', + "links -dump 'http://www.twingly.com/ping2?url=lateral.netmanagers.com.ar'", + 'rsync -rav ~/bartleblog-backup/* ralsina@netmanagers.com.ar:bartleblog-backup', + ] + +Other interesting ideas are using +`git as a deployment mechanism <http://toroid.org/ams/git-website-howto>`_ (or any other VCS +for that matter), using `lftp mirror <http://lftp.yar.ru/>`_ or unison, or dropbox, or +Ubuntu One. Any way you can think of to copy files from one place to another is good enough. + +Comments +-------- + +While Nikola creates static sites, there is a minimum level of user interaction you +are probably expecting: comments. + +The default templates contain support for `Disqus <http://disqus.com>`_. All you have +to do is register a forum, put its short name in the ``DISQUS_FORUM`` option. + +Disqus is a good option because: + +1) It doesn't require any server-side software on your site +2) They offer you a way to export your comments, so you can take + them with you if you need to. +3) It's free. +4) It's damn nice. + +.. admonition:: Important + + In some cases, when you run the test site, you won't see the comments. + That can be fixed by adding the disqus_developer flag to the templates + but it's probably more trouble than it's worth. + + +Image Galleries +--------------- + +To create an image gallery, all you have to do is add a folder inside ``galleries``, +and put images there. Nikola will take care of creating thumbnails, index page, etc. + +If you click on images on a gallery, you should see a bigger image, thanks to +the excellent `colorbox <http://www.jacklmoore.com/colorbox>`_ + +The gallery pages are generated using the ``gallery.tmpl`` template, and you can +customize it there (you could switch to another lightbox instead of colorbox, change +its settings, change the layout, etc.). + +The ``conf.py`` options affecting gallery pages are these:: + + # Galleries are folders in galleries/ + # Final location of galleries will be output / GALLERY_PATH / gallery_name + GALLERY_PATH = "galleries" + THUMBNAIL_SIZE = 180 + MAX_IMAGE_SIZE = 1280 + USE_FILENAME_AS_TITLE = True + +If you add a file in ``galleries/gallery_name/index.txt`` its contents will be +converted to HTML and inserted above the images in the gallery page. + +If you add some image filenames in ``galleries/gallery_name/exclude.meta``, they +will be excluded in the gallery page. + +If ``USE_FILENAME_AS_TITLE`` is True the filename (parsed as a readable string) +is used as the photo caption. If the filename starts with a number, it will +be stripped. For example ``03_an_amazing_sunrise.jpg`` will be render as *An amazing sunrise*. + +Here is a `demo gallery </galleries/demo>`_ of historic, public domain Nikola +Tesla pictures taken from `this site <http://kerryr.net/pioneers/gallery/tesla.htm>`_. + +Optimizing Your Website +----------------------- + +One of the main goals of Nikola is to make your site fast and light. So here are a few +tips we have found when setting up Nikola with Apache. If you have more, or +different ones, or about other webservers, please share! + +#. Use a speed testing tool. I used Yahoo's YSlow but you can use any of them, and + it's probably a good idea to use more than one. + +#. Enable compression in Apache:: + + AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css + +#. If even after you did the previous step the CSS files are not sent compressed:: + + AddType text/css .css + +In the future we will be adding HTML/CSS/JS minimization and image recompression but +that's not there yet, so you may want to use 3rd party tools to achieve that. + +Restructured Text Extensions +---------------------------- + +Nikola includes support for a few directives that are not part of docutils, but which +we think are handy for website development. + +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:: + + .. youtube:: 8N_tupPBtWQ + +code-block +~~~~~~~~~~ + +This is a somewhat complicated directive to display code nicely. You can just +embed code like this:: + + .. code-block:: python + + print "Hello World!" + +Or you can include the code from a file: + + .. code-block:: python + :include: /foo/bar/baz.py + +listing +~~~~~~~ + +To use this, you have to put your source code files inside ``listings`` or whatever your +``LISTINGS_FOLDER`` variable is set to. Assuming you have a ``foo.py`` inside that folder:: + + .. listing:: foo.py + +Will include the source code from ``foo.py`` and also create a ``listings/foo.py.html`` page +and the listing will have a title linking to it. + +Advanced Code Options +~~~~~~~~~~~~~~~~~~~~~ + +Both code-block and listing support a number of options, including these: + +start-at + A string, the diplayed code will start when it finds this +end-at + A string, the diplayed code will end when it finds this +start-after + A string, the diplayed code will start in the line after this +end-before + A string, the diplayed code will end in the line before this +linenos + Display line numbers +linenos_offset + Use the original file's line numbers (warning: broken) +tab-width + Size of the tabs (default 4) + +License +------- + +Nikola is released under the `GPL version 3 <http://www.gnu.org/licenses/gpl-3.0.html>`_ which +is a free software license. Some components shipped along with Nikola, or required by it are +released under other licenses. + +If you are not familiar with free software licensing: In general, you should be able to +do pretty much anything you want, unless you modify Nikola. If you modify it, and share +it with someone else, that someone else should get all your modifications under the same +license you got it. diff --git a/nikola/data/samplesite/stories/quickref.meta b/nikola/data/samplesite/stories/quickref.meta new file mode 100644 index 0000000..f8b0659 --- /dev/null +++ b/nikola/data/samplesite/stories/quickref.meta @@ -0,0 +1,4 @@ +A reStructuredText Reference +quickref +2012/03/30 23:00 + diff --git a/nikola/data/samplesite/stories/quickref.txt b/nikola/data/samplesite/stories/quickref.txt new file mode 100644 index 0000000..13ebc9b --- /dev/null +++ b/nikola/data/samplesite/stories/quickref.txt @@ -0,0 +1,1341 @@ +.. raw:: html + + <div class="alert alert-info pull-right" style="margin-left: 2em;"> + <h2><a name="contents">Contents</a></h2> + + <ul> + <li><a href="#inline-markup">Inline Markup</a></li> + <li><a href="#escaping">Escaping with Backslashes</a></li> + <li><a href="#section-structure">Section Structure</a></li> + <li><a href="#paragraphs">Paragraphs</a></li> + <li><a href="#bullet-lists">Bullet Lists</a></li> + <li><a href="#enumerated-lists">Enumerated Lists</a></li> + <li><a href="#definition-lists">Definition Lists</a></li> + <li><a href="#field-lists">Field Lists</a></li> + <li><a href="#option-lists">Option Lists</a></li> + <li><a href="#literal-blocks">Literal Blocks</a></li> + <li><a href="#line-blocks">Line Blocks</a></li> + <li><a href="#block-quotes">Block Quotes</a></li> + <li><a href="#doctest-blocks">Doctest Blocks</a></li> + <li><a href="#tables">Tables</a></li> + <li><a href="#transitions">Transitions</a></li> + <li><a href="#explicit-markup">Explicit Markup</a> + <ul> + <li><a href="#footnotes">Footnotes</a></li> + <li><a href="#citations">Citations</a></li> + <li><a href="#hyperlink-targets">Hyperlink Targets</a> + <ul> + <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> + <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> + <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> + <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> + </ul></li> + <li><a href="#directives">Directives</a></li> + <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> + <li><a href="#comments">Comments</a></li> + </ul></li> + <li><a href="#getting-help">Getting Help</a></li> + </ul> + </div> + + + <h1>Quick <i>re</i><font size="+4"><tt>Structured</tt></font><i>Text</i></h1> + + <!-- Caveat: if you're reading the HTML for the examples, --> + <!-- beware that it was hand-generated, not by Docutils/ReST. --> + + <blockquote> + <p>Copyright: This document has been placed in the public domain. + </blockquote> + + + <p>The full details of the markup may be found on the + <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> + page. This document is just intended as a reminder. + + <p>Links that look like "(<a href="#details">details</a>)" point + into the HTML version of the full <a + href="../../ref/rst/restructuredtext.html">reStructuredText + specification</a> document. These are relative links; if they + don't work, please use the <a + href="http://docutils.sourceforge.net/docs/user/rst/quickref.html" + >master "Quick reStructuredText"</a> document. + + + <h2><a href="#contents" name="inline-markup" class="backref" + >Inline Markup</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#inline-markup">details</a>) + + <p>Inline markup allows words and phrases within text to have + character styles (like italics and boldface) and functionality + (like hyperlinks). + + <p><table border="1" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th>Plain text + <th>Typical result + <th>Notes + </thead> + <tbody> + <tr valign="top"> + <td nowrap><samp>*emphasis*</samp> + <td><em>emphasis</em> + <td>Normally rendered as italics. + + <tr valign="top"> + <td nowrap><samp>**strong emphasis**</samp> + <td><strong>strong emphasis</strong> + <td>Normally rendered as boldface. + + <tr valign="top"> + <td nowrap><samp>`interpreted text`</samp> + <td>(see note at right) + <td>The rendering and <em>meaning</em> of interpreted text is + domain- or application-dependent. It can be used for things + like index entries or explicit descriptive markup (like program + identifiers). + + <tr valign="top"> + <td nowrap><samp>``inline literal``</samp> + <td><code>inline literal</code> + <td>Normally rendered as monospaced text. Spaces should be + preserved, but line breaks will not be. + + <tr valign="top"> + <td nowrap><samp>reference_</samp> + <td><a href="#hyperlink-targets">reference</a> + <td>A simple, one-word hyperlink reference. See <a + href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>`phrase reference`_</samp> + <td><a href="#hyperlink-targets">phrase reference</a> + <td>A hyperlink reference with spaces or punctuation needs to be + quoted with backquotes. See <a + href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>anonymous__</samp> + <td><a href="#hyperlink-targets">anonymous</a> + <td>With two underscores instead of one, both simple and phrase + references may be anonymous (the reference text is not repeated + at the target). See <a + href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>_`inline internal target`</samp> + <td><a name="inline-internal-target">inline internal target</a> + <td>A crossreference target within text. + See <a href="#hyperlink-targets">Hyperlink Targets</a>. + + <tr valign="top"> + <td nowrap><samp>|substitution reference|</samp> + <td>(see note at right) + <td>The result is substituted in from the <a + href="#substitution-references-and-definitions">substitution + definition</a>. It could be text, an image, a hyperlink, or a + combination of these and others. + + <tr valign="top"> + <td nowrap><samp>footnote reference [1]_</samp> + <td>footnote reference <sup><a href="#footnotes">1</a></sup> + <td>See <a href="#footnotes">Footnotes</a>. + + <tr valign="top"> + <td nowrap><samp>citation reference [CIT2002]_</samp> + <td>citation reference <a href="#citations">[CIT2002]</a> + <td>See <a href="#citations">Citations</a>. + + <tr valign="top"> + <td nowrap><samp>http://docutils.sf.net/</samp> + <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> + <td>A standalone hyperlink. + + </table> + + <p>Asterisk, backquote, vertical bar, and underscore are inline + delimiter characters. Asterisk, backquote, and vertical bar act + like quote marks; matching characters surround the marked-up word + or phrase, whitespace or other quoting is required outside them, + and there can't be whitespace just inside them. If you want to use + inline delimiter characters literally, <a href="#escaping">escape + (with backslash)</a> or quote them (with double backquotes; i.e. + use inline literals). + + <p>In detail, the reStructuredText specification says that in + inline markup, the following rules apply to start-strings and + end-strings (inline markup delimiters): + + <ol> + <li>The start-string must start a text block or be + immediately preceded by whitespace or any of + <samp>' " ( [ {</samp> or <samp><</samp>. + <li>The start-string must be immediately followed by non-whitespace. + <li>The end-string must be immediately preceded by non-whitespace. + <li>The end-string must end a text block (end of document or + followed by a blank line) or be immediately followed by whitespace + or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> + or <samp>></samp>. + <li>If a start-string is immediately preceded by one of + <samp>' " ( [ {</samp> or <samp><</samp>, it must not be + immediately followed by the corresponding character from + <samp>' " ) ] }</samp> or <samp>></samp>. + <li>An end-string must be separated by at least one + character from the start-string. + <li>An <a href="#escaping">unescaped</a> backslash preceding a + start-string or end-string will disable markup recognition, except + for the end-string of inline literals. + </ol> + + <p>Also remember that inline markup may not be nested (well, + except that inline literals can contain any of the other inline + markup delimiter characters, but that doesn't count because + nothing is processed). + + <h2><a href="#contents" name="escaping" class="backref" + >Escaping with Backslashes</a></h2> + + <p>(<a + href="../../ref/rst/restructuredtext.html#escaping-mechanism">details</a>) + + <p>reStructuredText uses backslashes ("\") to override the special + meaning given to markup characters and get the literal characters + themselves. To get a literal backslash, use an escaped backslash + ("\\"). For example: + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Raw reStructuredText + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"><td> + <samp>*escape* ``with`` "\"</samp> + <td><em>escape</em> <samp>with</samp> "" + <tr valign="top"><td> + <samp>\*escape* \``with`` "\\"</samp> + <td>*escape* ``with`` "\" + </table> + + <p>In Python strings it will, of course, be necessary + to escape any backslash characters so that they actually + <em>reach</em> reStructuredText. + The simplest way to do this is to use raw strings: + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Python string + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"><td> + <samp>r"""\*escape* \`with` "\\""""</samp> + <td>*escape* `with` "\" + <tr valign="top"><td> + <samp> """\\*escape* \\`with` "\\\\""""</samp> + <td>*escape* `with` "\" + <tr valign="top"><td> + <samp> """\*escape* \`with` "\\""""</samp> + <td><em>escape</em> with "" + </table> + + <h2><a href="#contents" name="section-structure" class="backref" + >Section Structure</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#sections">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>=====</samp> + <br><samp>Title</samp> + <br><samp>=====</samp> + <br><samp>Subtitle</samp> + <br><samp>--------</samp> + <br><samp>Titles are underlined (or over-</samp> + <br><samp>and underlined) with a printing</samp> + <br><samp>nonalphanumeric 7-bit ASCII</samp> + <br><samp>character. Recommended choices</samp> + <br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> + <br><samp>The underline/overline must be at</samp> + <br><samp>least as long as the title text.</samp> + <br><samp></samp> + <br><samp>A lone top-level (sub)section</samp> + <br><samp>is lifted up to be the document's</samp> + <br><samp>(sub)title.</samp> + + <td> + <font size="+2"><strong>Title</strong></font> + <p><font size="+1"><strong>Subtitle</strong></font> + <p>Titles are underlined (or over- + and underlined) with a printing + nonalphanumeric 7-bit ASCII + character. Recommended choices + are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". + The underline/overline must be at + least as long as the title text. + <p>A lone top-level (sub)section is + lifted up to be the document's + (sub)title. + </table> + + <h2><a href="#contents" name="paragraphs" class="backref" + >Paragraphs</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#paragraphs">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp>This is a paragraph.</samp> + + <p><samp>Paragraphs line up at their left</samp> + <br><samp>edges, and are normally separated</samp> + <br><samp>by blank lines.</samp> + + <td> + <p>This is a paragraph. + + <p>Paragraphs line up at their left edges, and are normally + separated by blank lines. + + </table> + + <h2><a href="#contents" name="bullet-lists" class="backref" + >Bullet Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#bullet-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>Bullet lists:</samp> + + <p><samp>- This is item 1</samp> + <br><samp>- This is item 2</samp> + + <p><samp>- Bullets are "-", "*" or "+".</samp> + <br><samp> Continuing text must be aligned</samp> + <br><samp> after the bullet and whitespace.</samp> + + <p><samp>Note that a blank line is required</samp> + <br><samp>before the first item and after the</samp> + <br><samp>last, but is optional between items.</samp> + <td>Bullet lists: + <ul> + <li>This is item 1 + <li>This is item 2 + <li>Bullets are "-", "*" or "+". + Continuing text must be aligned + after the bullet and whitespace. + </ul> + <p>Note that a blank line is required before the first + item and after the last, but is optional between items. + </table> + + <h2><a href="#contents" name="enumerated-lists" class="backref" + >Enumerated Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#enumerated-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>Enumerated lists:</samp> + + <p><samp>3. This is the first item</samp> + <br><samp>4. This is the second item</samp> + <br><samp>5. Enumerators are arabic numbers,</samp> + <br><samp> single letters, or roman numerals</samp> + <br><samp>6. List items should be sequentially</samp> + <br><samp> numbered, but need not start at 1</samp> + <br><samp> (although not all formatters will</samp> + <br><samp> honour the first index).</samp> + <br><samp>#. This item is auto-enumerated</samp> + <td>Enumerated lists: + <ol type="1"> + <li value="3">This is the first item + <li>This is the second item + <li>Enumerators are arabic numbers, single letters, + or roman numerals + <li>List items should be sequentially numbered, + but need not start at 1 (although not all + formatters will honour the first index). + <li>This item is auto-enumerated + </ol> + </table> + + <h2><a href="#contents" name="definition-lists" class="backref" + >Definition Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#definition-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>Definition lists:</samp> + <br> + <br><samp>what</samp> + <br><samp> Definition lists associate a term with</samp> + <br><samp> a definition.</samp> + <br> + <br><samp>how</samp> + <br><samp> The term is a one-line phrase, and the</samp> + <br><samp> definition is one or more paragraphs or</samp> + <br><samp> body elements, indented relative to the</samp> + <br><samp> term. Blank lines are not allowed</samp> + <br><samp> between term and definition.</samp> + <td>Definition lists: + <dl> + <dt><strong>what</strong> + <dd>Definition lists associate a term with + a definition. + + <dt><strong>how</strong> + <dd>The term is a one-line phrase, and the + definition is one or more paragraphs or + body elements, indented relative to the + term. Blank lines are not allowed + between term and definition. + </dl> + </table> + + <h2><a href="#contents" name="field-lists" class="backref" + >Field Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#field-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>:Authors:</samp> + <br><samp> Tony J. (Tibs) Ibbs,</samp> + <br><samp> David Goodger</samp> + + <p><samp> (and sundry other good-natured folks)</samp> + + <p><samp>:Version: 1.0 of 2001/08/08</samp> + <br><samp>:Dedication: To my father.</samp> + <td> + <table> + <tr valign="top"> + <td><strong>Authors:</strong> + <td>Tony J. (Tibs) Ibbs, + David Goodger + <tr><td><td>(and sundry other good-natured folks) + <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 + <tr><td><strong>Dedication:</strong><td>To my father. + </table> + </table> + + <p>Field lists are used as part of an extension syntax, such as + options for <a href="#directives">directives</a>, or database-like + records meant for further processing. Field lists may also be + used as generic two-column table constructs in documents. + + <h2><a href="#contents" name="option-lists" class="backref" + >Option Lists</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#option-lists">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp> + -a command-line option "a" + <br>-b file options can have arguments + <br> and long descriptions + <br>--long options can be long also + <br>--input=file long options can also have + <br> arguments + <br>/V DOS/VMS-style options too + </samp> + + <td> + <table border="0" width="100%"> + <tbody valign="top"> + <tr> + <td width="30%"><samp>-a</samp> + <td>command-line option "a" + <tr> + <td><samp>-b <i>file</i></samp> + <td>options can have arguments and long descriptions + <tr> + <td><samp>--long</samp> + <td>options can be long also + <tr> + <td><samp>--input=<i>file</i></samp> + <td>long options can also have arguments + <tr> + <td><samp>/V</samp> + <td>DOS/VMS-style options too + </table> + </table> + + <p>There must be at least two spaces between the option and the + description. + + <h2><a href="#contents" name="literal-blocks" class="backref" + >Literal Blocks</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#literal-blocks">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>A paragraph containing only two colons</samp> + <br><samp>indicates that the following indented</samp> + <br><samp>or quoted text is a literal block.</samp> + <br> + <br><samp>::</samp> + <br> + <br><samp> Whitespace, newlines, blank lines, and</samp> + <br><samp> all kinds of markup (like *this* or</samp> + <br><samp> \this) is preserved by literal blocks.</samp> + <br> + <br><samp> The paragraph containing only '::'</samp> + <br><samp> will be omitted from the result.</samp> + <br> + <br><samp>The ``::`` may be tacked onto the very</samp> + <br><samp>end of any paragraph. The ``::`` will be</samp> + <br><samp>omitted if it is preceded by whitespace.</samp> + <br><samp>The ``::`` will be converted to a single</samp> + <br><samp>colon if preceded by text, like this::</samp> + <br> + <br><samp> It's very convenient to use this form.</samp> + <br> + <br><samp>Literal blocks end when text returns to</samp> + <br><samp>the preceding paragraph's indentation.</samp> + <br><samp>This means that something like this</samp> + <br><samp>is possible::</samp> + <br> + <br><samp> We start here</samp> + <br><samp> and continue here</samp> + <br><samp> and end here.</samp> + <br> + <br><samp>Per-line quoting can also be used on</samp> + <br><samp>unindented literal blocks::</samp> + <br> + <br><samp>> Useful for quotes from email and</samp> + <br><samp>> for Haskell literate programming.</samp> + + <td> + <p>A paragraph containing only two colons + indicates that the following indented or quoted + text is a literal block. + + <pre> + Whitespace, newlines, blank lines, and + all kinds of markup (like *this* or + \this) is preserved by literal blocks. + + The paragraph containing only '::' + will be omitted from the result.</pre> + + <p>The <samp>::</samp> may be tacked onto the very + end of any paragraph. The <samp>::</samp> will be + omitted if it is preceded by whitespace. + The <samp>::</samp> will be converted to a single + colon if preceded by text, like this: + + <pre> + It's very convenient to use this form.</pre> + + <p>Literal blocks end when text returns to + the preceding paragraph's indentation. + This means that something like this is possible: + + <pre> + We start here + and continue here + and end here.</pre> + + <p>Per-line quoting can also be used on + unindented literal blocks: + + <pre> + > Useful for quotes from email and + > for Haskell literate programming.</pre> + </table> + + <h2><a href="#contents" name="line-blocks" class="backref" + >Line Blocks</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#line-blocks">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>| Line blocks are useful for addresses,</samp> + <br><samp>| verse, and adornment-free lists.</samp> + <br><samp>|</samp> + <br><samp>| Each new line begins with a</samp> + <br><samp>| vertical bar ("|").</samp> + <br><samp>| Line breaks and initial indents</samp> + <br><samp>| are preserved.</samp> + <br><samp>| Continuation lines are wrapped</samp> + <br><samp> portions of long lines; they begin</samp> + <br><samp> with spaces in place of vertical bars.</samp> + + <td> + <div class="line-block"> + <div class="line">Line blocks are useful for addresses,</div> + <div class="line">verse, and adornment-free lists.</div> + <div class="line"><br /></div> + <div class="line">Each new line begins with a</div> + <div class="line">vertical bar ("|").</div> + <div class="line-block"> + <div class="line">Line breaks and initial indents</div> + <div class="line">are preserved.</div> + </div> + <div class="line">Continuation lines are wrapped portions + of long lines; they begin + with spaces in place of vertical bars.</div> + </div> + </table> + + <h2><a href="#contents" name="block-quotes" class="backref" + >Block Quotes</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#block-quotes">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <samp>Block quotes are just:</samp> + + <p><samp> Indented paragraphs,</samp> + + <p><samp> and they may nest.</samp> + <td> + Block quotes are just: + <blockquote> + <p>Indented paragraphs, + <blockquote> + <p>and they may nest. + </blockquote> + </blockquote> + </table> + + <p>Use <a href="#comments">empty comments</a> to separate indentation + contexts, such as block quotes and directive contents.</p> + + <h2><a href="#contents" name="doctest-blocks" class="backref" + >Doctest Blocks</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#doctest-blocks">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp>Doctest blocks are interactive + <br>Python sessions. They begin with + <br>"``>>>``" and end with a blank line.</samp> + + <p><samp>>>> print "This is a doctest block." + <br>This is a doctest block.</samp> + + <td> + <p>Doctest blocks are interactive + Python sessions. They begin with + "<samp>>>></samp>" and end with a blank line. + + <p><samp>>>> print "This is a doctest block." + <br>This is a doctest block.</samp> + </table> + + <p>"The <a + href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a> + module searches a module's docstrings for text that looks like an + interactive Python session, then executes all such sessions to + verify they still work exactly as shown." (From the doctest docs.) + + <h2><a href="#contents" name="tables" class="backref" + >Tables</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#tables">details</a>) + + <p>There are two syntaxes for tables in reStructuredText. Grid + tables are complete but cumbersome to create. Simple tables are + easy to create but limited (no row spans, etc.).</p> + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp>Grid table:</samp></p> + + <p><samp>+------------+------------+-----------+</samp> + <br><samp>| Header 1 | Header 2 | Header 3 |</samp> + <br><samp>+============+============+===========+</samp> + <br><samp>| body row 1 | column 2 | column 3 |</samp> + <br><samp>+------------+------------+-----------+</samp> + <br><samp>| body row 2 | Cells may span columns.|</samp> + <br><samp>+------------+------------+-----------+</samp> + <br><samp>| body row 3 | Cells may | - Cells |</samp> + <br><samp>+------------+ span rows. | - contain |</samp> + <br><samp>| body row 4 | | - blocks. |</samp> + <br><samp>+------------+------------+-----------+</samp></p> + <td> + <p>Grid table:</p> + <table border="1"> + <thead valign="bottom"> + <tr> + <th>Header 1 + <th>Header 2 + <th>Header 3 + </tr> + </thead> + <tbody valign="top"> + <tr> + <td>body row 1 + <td>column 2 + <td>column 3 + </tr> + <tr> + <td>body row 2 + <td colspan="2">Cells may span columns. + </tr> + <tr> + <td>body row 3 + <td rowspan="2">Cells may<br>span rows. + <td rowspan="2"> + <ul> + <li>Cells + <li>contain + <li>blocks. + </ul> + </tr> + <tr> + <td>body row 4 + </tr> + </table> + <tr valign="top"> + <td> + <p><samp>Simple table:</samp></p> + + <p><samp>===== ===== ======</samp> + <br><samp> Inputs Output</samp> + <br><samp>------------ ------</samp> + <br><samp> A B A or B</samp> + <br><samp>===== ===== ======</samp> + <br><samp>False False False</samp> + <br><samp>True False True</samp> + <br><samp>False True True</samp> + <br><samp>True True True</samp> + <br><samp>===== ===== ======</samp></p> + + <td> + <p>Simple table:</p> + <table border="1"> + <colgroup> + <col width="31%"> + <col width="31%"> + <col width="38%"> + </colgroup> + <thead valign="bottom"> + <tr> + <th colspan="2">Inputs + <th>Output + <tr> + <th>A + <th>B + <th>A or B + <tbody valign="top"> + <tr> + <td>False + <td>False + <td>False + <tr> + <td>True + <td>False + <td>True + <tr> + <td>False + <td>True + <td>True + <tr> + <td>True + <td>True + <td>True + </table> + + </table> + + <h2><a href="#contents" name="transitions" class="backref" + >Transitions</a></h2> + + <p>(<a href="../../ref/rst/restructuredtext.html#transitions">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td> + <p><samp> + A transition marker is a horizontal line + <br>of 4 or more repeated punctuation + <br>characters.</samp> + + <p><samp>------------</samp> + + <p><samp>A transition should not begin or end a + <br>section or document, nor should two + <br>transitions be immediately adjacent.</samp> + + <td> + <p>A transition marker is a horizontal line + of 4 or more repeated punctuation + characters.</p> + + <hr> + + <p>A transition should not begin or end a + section or document, nor should two + transitions be immediately adjacent. + </table> + + <p>Transitions are commonly seen in novels and short fiction, as a + gap spanning one or more lines, marking text divisions or + signaling changes in subject, time, point of view, or emphasis. + + <h2><a href="#contents" name="explicit-markup" class="backref" + >Explicit Markup</a></h2> + + <p>Explicit markup blocks are used for constructs which float + (footnotes), have no direct paper-document representation + (hyperlink targets, comments), or require specialized processing + (directives). They all begin with two periods and whitespace, the + "explicit markup start". + + <h3><a href="#contents" name="footnotes" class="backref" + >Footnotes</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#footnotes">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Footnote references, like [5]_.</samp> + <br><samp>Note that footnotes may get</samp> + <br><samp>rearranged, e.g., to the bottom of</samp> + <br><samp>the "page".</samp> + + <p><samp>.. [5] A numerical footnote. Note</samp> + <br><samp> there's no colon after the ``]``.</samp> + + <td> + Footnote references, like <sup><a href="#5">5</a></sup>. + Note that footnotes may get rearranged, e.g., to the bottom of + the "page". + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. + Note there's no colon after the <samp>]</samp>. + </table> + + <tr valign="top"> + <td> + <samp>Autonumbered footnotes are</samp> + <br><samp>possible, like using [#]_ and [#]_.</samp> + <p><samp>.. [#] This is the first one.</samp> + <br><samp>.. [#] This is the second one.</samp> + + <p><samp>They may be assigned 'autonumber</samp> + <br><samp>labels' - for instance, + <br>[#fourth]_ and [#third]_.</samp> + + <p><samp>.. [#third] a.k.a. third_</samp> + <p><samp>.. [#fourth] a.k.a. fourth_</samp> + <td> + Autonumbered footnotes are possible, like using <sup><a + href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. + + <p>They may be assigned 'autonumber labels' - for instance, + <sup><a href="#fourth">4</a></sup> and <sup><a + href="#third">3</a></sup>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. + <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. + <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> + <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> + </table> + + <tr valign="top"> + <td> + <samp>Auto-symbol footnotes are also</samp> + <br><samp>possible, like this: [*]_ and [*]_.</samp> + <p><samp>.. [*] This is the first one.</samp> + <br><samp>.. [*] This is the second one.</samp> + + <td> + Auto-symbol footnotes are also + possible, like this: <sup><a href="#symbol1">*</a></sup> + and <sup><a href="#symbol2">†</a></sup>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Footnotes: --> + <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote + <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. + </table> + + </table> + + <p>The numbering of auto-numbered footnotes is determined by the + order of the footnotes, not of the references. For auto-numbered + footnote references without autonumber labels + ("<samp>[#]_</samp>"), the references and footnotes must be in the + same relative order. Similarly for auto-symbol footnotes + ("<samp>[*]_</samp>"). + + <h3><a href="#contents" name="citations" class="backref" + >Citations</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#citations">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Citation references, like [CIT2002]_.</samp> + <br><samp>Note that citations may get</samp> + <br><samp>rearranged, e.g., to the bottom of</samp> + <br><samp>the "page".</samp> + + <p><samp>.. [CIT2002] A citation</samp> + <br><samp> (as often used in journals).</samp> + + <p><samp>Citation labels contain alphanumerics,</samp> + <br><samp>underlines, hyphens and fullstops.</samp> + <br><samp>Case is not significant.</samp> + + <p><samp>Given a citation like [this]_, one</samp> + <br><samp>can also refer to it like this_.</samp> + + <p><samp>.. [this] here.</samp> + + <td> + Citation references, like <a href="#cit2002">[CIT2002]</a>. + Note that citations may get rearranged, e.g., to the bottom of + the "page". + + <p>Citation labels contain alphanumerics, underlines, hyphens + and fullstops. Case is not significant. + + <p>Given a citation like <a href="#this">[this]</a>, one + can also refer to it like <a href="#this">this</a>. + + <p><table> + <tr><td colspan="2"><hr> + <!-- <tr><td colspan="2">Citations: --> + <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation + (as often used in journals). + <tr><td><a name="this"><strong>[this]</strong></a><td> here. + </table> + + </table> + + <h3><a href="#contents" name="hyperlink-targets" class="backref" + >Hyperlink Targets</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#hyperlink-targets">details</a>) + + <h4><a href="#contents" name="external-hyperlink-targets" class="backref" + >External Hyperlink Targets</a></h4> + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td rowspan="2"> + <samp>External hyperlinks, like Python_.</samp> + + <p><samp>.. _Python: http://www.python.org/</samp> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> + <tr><td>External hyperlinks, like + <a href="http://www.python.org/">Python</a>. + </table> + <tr valign="top"> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Call-out form</em> + <tr><td>External hyperlinks, like + <a href="#labPython"><i>Python</i></a>. + + <p><table> + <tr><td colspan="2"><hr> + <tr><td><a name="labPython"><i>Python:</i></a> + <td> <a href="http://www.python.org/">http://www.python.org/</a> + </table> + </table> + </table> + + <p>"<em>Fold-in</em>" is the representation typically used in HTML + documents (think of the indirect hyperlink being "folded in" like + ingredients into a cake), and "<em>call-out</em>" is more suitable for + printed documents, where the link needs to be presented explicitly, for + example as a footnote. You can force usage of the call-out form by + using the + "<a href="../../ref/rst/directives.html#target-notes">target-notes</a>" + directive. + + <p>reStructuredText also provides for <b>embedded URIs</b> (<a + href="../../ref/rst/restructuredtext.html#embedded-uris">details</a>), + a convenience at the expense of readability. A hyperlink + reference may directly embed a target URI inline, within angle + brackets. The following is exactly equivalent to the example above: + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td rowspan="2"> + <samp>External hyperlinks, like `Python + <br><http://www.python.org/>`_.</samp> + <td>External hyperlinks, like + <a href="http://www.python.org/">Python</a>. + </table> + + <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" + >Internal Hyperlink Targets</a></h4> + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td rowspan="2"><samp>Internal crossreferences, like example_.</samp> + + <p><samp>.. _example:</samp> + + <p><samp>This is an example crossreference target.</samp> + <td> + <table width="100%"> + <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> + <!-- Note that some browsers may not like an "a" tag that --> + <!-- does not have any content, so we could arbitrarily --> + <!-- use the first word as content - *or* just trust to --> + <!-- luck! --> + <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> + <p><a name="example-foldin">This</a> is an example + crossreference target. + </table> + <tr valign="top"> + <td> + <table width="100%"> + <tr><td bgcolor="#99CCFF"><em>Call-out form</em> + <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> + + <p><a name="example-callout"><i>example:</i></a> + <br>This is an example crossreference target. + </table> + + </table> + + <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" + >Indirect Hyperlink Targets</a></h4> + + <p>(<a href="../../ref/rst/restructuredtext.html#indirect-hyperlink-targets">details</a>) + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Python_ is `my favourite + <br>programming language`__.</samp> + + <p><samp>.. _Python: http://www.python.org/</samp> + + <p><samp>__ Python_</samp> + + <td> + <p><a href="http://www.python.org/">Python</a> is + <a href="http://www.python.org/">my favourite + programming language</a>. + + </table> + + <p>The second hyperlink target (the line beginning with + "<samp>__</samp>") is both an indirect hyperlink target + (<i>indirectly</i> pointing at the Python website via the + "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink + target</b>. In the text, a double-underscore suffix is used to + indicate an <b>anonymous hyperlink reference</b>. In an anonymous + hyperlink target, the reference text is not repeated. This is + useful for references with long text or throw-away references, but + the target should be kept close to the reference to prevent them + going out of sync. + + <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" + >Implicit Hyperlink Targets</a></h4> + + <p>(<a href="../../ref/rst/restructuredtext.html#implicit-hyperlink-targets">details</a>) + + <p>Section titles, footnotes, and citations automatically generate + hyperlink targets (the title text or footnote/citation label is + used as the hyperlink name). + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead><tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + + <tr valign="top"> + <td> + <samp>Titles are targets, too</samp> + <br><samp>=======================</samp> + <br><samp>Implict references, like `Titles are</samp> + <br><samp>targets, too`_.</samp> + <td> + <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> + <p>Implict references, like <a href="#title">Titles are + targets, too</a>. + </table> + + <h3><a href="#contents" name="directives" class="backref" + >Directives</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#directives">details</a>) + + <p>Directives are a general-purpose extension mechanism, a way of + adding support for new constructs without adding new syntax. For + a description of all standard directives, see <a + href="../../ref/rst/directives.html" >reStructuredText + Directives</a>. + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td><samp>For instance:</samp> + + <p><samp>.. image:: images/ball1.gif</samp> + + <td> + For instance: + <p><img src="images/ball1.gif" alt="ball1"> + </table> + + <h3><a href="#contents" name="substitution-references-and-definitions" + class="backref" >Substitution References and Definitions</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#substitution-definitions">details</a>) + + <p>Substitutions are like inline directives, allowing graphics and + arbitrary constructs within text. + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td><samp> + The |biohazard| symbol must be + used on containers used to + dispose of medical waste.</samp> + + <p><samp> + .. |biohazard| image:: biohazard.png</samp> + + <td> + + <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol + must be used on containers used to dispose of medical waste. + + </table> + + <h3><a href="#contents" name="comments" class="backref" + >Comments</a></h3> + + <p>(<a href="../../ref/rst/restructuredtext.html#comments">details</a>) + + <p>Any text which begins with an explicit markup start but doesn't + use the syntax of any of the constructs above, is a comment. + + <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> + <thead> + <tr align="left" bgcolor="#99CCFF"> + <th width="50%">Plain text + <th width="50%">Typical result + </thead> + <tbody> + <tr valign="top"> + <td><samp>.. This text will not be shown</samp> + <br><samp> (but, for instance, in HTML might be</samp> + <br><samp> rendered as an HTML comment)</samp> + + <td> + <!-- This text will not be shown --> + <!-- (but, for instance in HTML might be --> + <!-- rendered as an HTML comment) --> + + <tr valign="top"> + <td> + <samp>An "empty comment" does not</samp> + <br><samp>consume following blocks.</samp> + <br><samp>(An empty comment is ".." with</samp> + <br><samp>blank lines before and after.)</samp> + <p><samp>..</samp> + <p><samp> So this block is not "lost",</samp> + <br><samp> despite its indentation.</samp> + <td> + An "empty comment" does not + consume following blocks. + (An empty comment is ".." with + blank lines before and after.) + <blockquote> + So this block is not "lost", + despite its indentation. + </blockquote> + </table> + + <h2><a href="#contents" name="getting-help" class="backref" + >Getting Help</a></h2> + + <p>Users who have questions or need assistance with Docutils or + reStructuredText should <a + href="mailto:docutils-users@lists.sourceforge.net" >post a + message</a> to the <a + href="http://lists.sourceforge.net/lists/listinfo/docutils-users" + >Docutils-Users mailing list</a>. The <a + href="http://docutils.sourceforge.net/" >Docutils project web + site</a> has more information. + + <p><hr> + <address> + <p>Authors: + <a href="http://www.tibsnjoan.co.uk/">Tibs</a> + (<a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) + and David Goodger + (<a href="mailto:goodger@python.org">goodger@python.org</a>) + </address> + <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> diff --git a/nikola/data/samplesite/stories/quickstart.meta b/nikola/data/samplesite/stories/quickstart.meta new file mode 100644 index 0000000..ec9e8b5 --- /dev/null +++ b/nikola/data/samplesite/stories/quickstart.meta @@ -0,0 +1,4 @@ +A reStructuredText Primer +quickstart +2012/03/30 23:00 + diff --git a/nikola/data/samplesite/stories/quickstart.txt b/nikola/data/samplesite/stories/quickstart.txt new file mode 100644 index 0000000..a74d8fa --- /dev/null +++ b/nikola/data/samplesite/stories/quickstart.txt @@ -0,0 +1,406 @@ +A ReStructuredText Primer +========================= + +:Author: Richard Jones +:Version: $Revision: 5801 $ +:Copyright: This document has been placed in the public domain. + +.. class:: alert alert-info pull-left + +.. contents:: + + +The text below contains links that look like "(quickref__)". These +are relative links that point to the `Quick reStructuredText`_ user +reference. If these links don't work, please refer to the `master +quick reference`_ document. + +__ +.. _Quick reStructuredText: quickref.html +.. _master quick reference: + http://docutils.sourceforge.net/docs/user/rst/quickref.html + +.. Note:: This document is an informal introduction to + reStructuredText. The `What Next?`_ section below has links to + further resources, including a formal reference. + + +Structure +--------- + +From the outset, let me say that "Structured Text" is probably a bit +of a misnomer. It's more like "Relaxed Text" that uses certain +consistent patterns. These patterns are interpreted by a HTML +converter to produce "Very Structured Text" that can be used by a web +browser. + +The most basic pattern recognised is a **paragraph** (quickref__). +That's a chunk of text that is separated by blank lines (one is +enough). Paragraphs must have the same indentation -- that is, line +up at their left edge. Paragraphs that start indented will result in +indented quote paragraphs. For example:: + + This is a paragraph. It's quite + short. + + This paragraph will result in an indented block of + text, typically used for quoting other text. + + This is another one. + +Results in: + + This is a paragraph. It's quite + short. + + This paragraph will result in an indented block of + text, typically used for quoting other text. + + This is another one. + +__ quickref.html#paragraphs + + +Text styles +----------- + +(quickref__) + +__ quickref.html#inline-markup + +Inside paragraphs and other bodies of text, you may additionally mark +text for *italics* with "``*italics*``" or **bold** with +"``**bold**``". This is called "inline markup". + +If you want something to appear as a fixed-space literal, use +"````double back-quotes````". Note that no further fiddling is done +inside the double back-quotes -- so asterisks "``*``" etc. are left +alone. + +If you find that you want to use one of the "special" characters in +text, it will generally be OK -- reStructuredText is pretty smart. +For example, this lone asterisk * is handled just fine, as is the +asterisk in this equation: 5*6=30. If you actually +want text \*surrounded by asterisks* to **not** be italicised, then +you need to indicate that the asterisk is not special. You do this by +placing a backslash just before it, like so "``\*``" (quickref__), or +by enclosing it in double back-quotes (inline literals), like this:: + + ``*`` + +__ quickref.html#escaping + +.. Tip:: Think of inline markup as a form of (parentheses) and use it + the same way: immediately before and after the text being marked + up. Inline markup by itself (surrounded by whitespace) or in the + middle of a word won't be recognized. See the `markup spec`__ for + full details. + +__ ../../ref/rst/restructuredtext.html#inline-markup + + +Lists +----- + +Lists of items come in three main flavours: **enumerated**, +**bulleted** and **definitions**. In all list cases, you may have as +many paragraphs, sublists, etc. as you want, as long as the left-hand +side of the paragraph or whatever aligns with the first line of text +in the list item. + +Lists must always start a new paragraph -- that is, they must appear +after a blank line. + +**enumerated** lists (numbers, letters or roman numerals; quickref__) + __ quickref.html#enumerated-lists + + Start a line off with a number or letter followed by a period ".", + right bracket ")" or surrounded by brackets "( )" -- whatever you're + comfortable with. All of the following forms are recognised:: + + 1. numbers + + A. upper-case letters + and it goes over many lines + + with two paragraphs and all! + + a. lower-case letters + + 3. with a sub-list starting at a different number + 4. make sure the numbers are in the correct sequence though! + + I. upper-case roman numerals + + i. lower-case roman numerals + + (1) numbers again + + 1) and again + + Results in (note: the different enumerated list styles are not + always supported by every web browser, so you may not get the full + effect here): + + 1. numbers + + A. upper-case letters + and it goes over many lines + + with two paragraphs and all! + + a. lower-case letters + + 3. with a sub-list starting at a different number + 4. make sure the numbers are in the correct sequence though! + + I. upper-case roman numerals + + i. lower-case roman numerals + + (1) numbers again + + 1) and again + +**bulleted** lists (quickref__) + __ quickref.html#bullet-lists + + Just like enumerated lists, start the line off with a bullet point + character - either "-", "+" or "*":: + + * a bullet point using "*" + + - a sub-list using "-" + + + yet another sub-list + + - another item + + Results in: + + * a bullet point using "*" + + - a sub-list using "-" + + + yet another sub-list + + - another item + +**definition** lists (quickref__) + __ quickref.html#definition-lists + + Unlike the other two, the definition lists consist of a term, and + the definition of that term. The format of a definition list is:: + + what + Definition lists associate a term with a definition. + + *how* + The term is a one-line phrase, and the definition is one or more + paragraphs or body elements, indented relative to the term. + Blank lines are not allowed between term and definition. + + Results in: + + what + Definition lists associate a term with a definition. + + *how* + The term is a one-line phrase, and the definition is one or more + paragraphs or body elements, indented relative to the term. + Blank lines are not allowed between term and definition. + + +Preformatting (code samples) +---------------------------- +(quickref__) + +__ quickref.html#literal-blocks + +To just include a chunk of preformatted, never-to-be-fiddled-with +text, finish the prior paragraph with "``::``". The preformatted +block is finished when the text falls back to the same indentation +level as a paragraph prior to the preformatted block. For example:: + + An example:: + + Whitespace, newlines, blank lines, and all kinds of markup + (like *this* or \this) is preserved by literal blocks. + Lookie here, I've dropped an indentation level + (but not far enough) + + no more example + +Results in: + + An example:: + + Whitespace, newlines, blank lines, and all kinds of markup + (like *this* or \this) is preserved by literal blocks. + Lookie here, I've dropped an indentation level + (but not far enough) + + no more example + +Note that if a paragraph consists only of "``::``", then it's removed +from the output:: + + :: + + This is preformatted text, and the + last "::" paragraph is removed + +Results in: + +:: + + This is preformatted text, and the + last "::" paragraph is removed + + +Sections +-------- + +(quickref__) + +__ quickref.html#section-structure + +To break longer text up into sections, you use **section headers**. +These are a single line of text (one or more words) with adornment: an +underline alone, or an underline and an overline together, in dashes +"``-----``", equals "``======``", tildes "``~~~~~~``" or any of the +non-alphanumeric characters ``= - ` : ' " ~ ^ _ * + # < >`` that you +feel comfortable with. An underline-only adornment is distinct from +an overline-and-underline adornment using the same character. The +underline/overline must be at least as long as the title text. Be +consistent, since all sections marked with the same adornment style +are deemed to be at the same level:: + + Chapter 1 Title + =============== + + Section 1.1 Title + ----------------- + + Subsection 1.1.1 Title + ~~~~~~~~~~~~~~~~~~~~~~ + + Section 1.2 Title + ----------------- + + Chapter 2 Title + =============== + +This results in the following structure, illustrated by simplified +pseudo-XML:: + + <section> + <title> + Chapter 1 Title + <section> + <title> + Section 1.1 Title + <section> + <title> + Subsection 1.1.1 Title + <section> + <title> + Section 1.2 Title + <section> + <title> + Chapter 2 Title + +(Pseudo-XML uses indentation for nesting and has no end-tags. It's +not possible to show actual processed output, as in the other +examples, because sections cannot exist inside block quotes. For a +concrete example, compare the section structure of this document's +source text and processed output.) + +Note that section headers are available as link targets, just using +their name. To link to the Lists_ heading, I write "``Lists_``". If +the heading has a space in it like `text styles`_, we need to quote +the heading "```text styles`_``". + + +Document Title / Subtitle +````````````````````````` + +The title of the whole document is distinct from section titles and +may be formatted somewhat differently (e.g. the HTML writer by default +shows it as a centered heading). + +To indicate the document title in reStructuredText, use a unique adornment +style at the beginning of the document. To indicate the document subtitle, +use another unique adornment style immediately after the document title. For +example:: + + ================ + Document Title + ================ + ---------- + Subtitle + ---------- + + Section Title + ============= + + ... + +Note that "Document Title" and "Section Title" above both use equals +signs, but are distict and unrelated styles. The text of +overline-and-underlined titles (but not underlined-only) may be inset +for aesthetics. + + +Images +------ + +(quickref__) + +__ quickref.html#directives + +To include an image in your document, you use the the ``image`` directive__. +For example:: + + .. image:: images/biohazard.png + +results in: + +.. image:: images/biohazard.png + +The ``images/biohazard.png`` part indicates the filename of the image +you wish to appear in the document. There's no restriction placed on +the image (format, size etc). If the image is to appear in HTML and +you wish to supply additional information, you may:: + + .. image:: images/biohazard.png + :height: 100 + :width: 200 + :scale: 50 + :alt: alternate text + +See the full `image directive documentation`__ for more info. + +__ ../../ref/rst/directives.html +__ ../../ref/rst/directives.html#images + + +What Next? +---------- + +This primer introduces the most common features of reStructuredText, +but there are a lot more to explore. The `Quick reStructuredText`_ +user reference is a good place to go next. For complete details, the +`reStructuredText Markup Specification`_ is the place to go [#]_. + +Users who have questions or need assistance with Docutils or +reStructuredText should post a message to the Docutils-users_ mailing +list. + +.. [#] If that relative link doesn't work, try the master document: + http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html. + +.. _reStructuredText Markup Specification: + ../../ref/rst/restructuredtext.html +.. _Docutils-users: ../mailing-lists.html#docutils-users +.. _Docutils project web site: http://docutils.sourceforge.net/ diff --git a/nikola/data/samplesite/stories/theming.meta b/nikola/data/samplesite/stories/theming.meta new file mode 100644 index 0000000..db0832f --- /dev/null +++ b/nikola/data/samplesite/stories/theming.meta @@ -0,0 +1,3 @@ +Theming Nikola +theming +2012/03/13 12:00 diff --git a/nikola/data/samplesite/stories/theming.txt b/nikola/data/samplesite/stories/theming.txt new file mode 100644 index 0000000..339ecd4 --- /dev/null +++ b/nikola/data/samplesite/stories/theming.txt @@ -0,0 +1,236 @@ +Theming Nikola +============== + +:Version: 2.1+svn +:Author: Roberto Alsina <ralsina@netmanagers.com.ar> + +.. class:: alert alert-info pull-right + +.. contents:: + +The Structure +------------- + +Themes are located in the ``themes`` folder where Nikola is installed, one folder per theme. +The folder name is the theme name. + +A Nikola theme consists of three folders: + +assets + This is where you would put your CSS, Javascript and image files. It will be copied + into ``output/assets`` when you build the site, and the templates will contain + references to them. + + The included themes use `Bootstrap <http://twitter.github.com/bootstrap/>`_ + and `Colorbox <http://www.jacklmoore.com/colorbox>`_ so they are in assets, + along with CSS files for syntax highligting and reStructuredText, and a + minified copy of jQuery. + + If you want to base your theme on other frameworks (or on no framework at all) + just remember to put there everything you need for deployment. + +templates + This contains the templates used to generate the pages. While Nikola will use a + certain set of template names by default, you can add others for specific parts + of your site. + +messages + Nikola tries to be multilingual. This is where you put the strings for your theme + so that it can be translated into other languages. + +And these optional files: + +parent + A text file that, on its first line, contains the name of the **parent theme**. + Any resources missing on this theme, will be looked up in the parent theme + (and then in the grandparent, etc). + + The ``parent`` is so you don't have to create a full theme each time: just create an + empty theme, set the parent, and add the bits you want modified. + +engine + A text file which, on the first line, contains the name of the template engine + this theme needs. Currently supported values are "mako" and "jinja". + If this file is not given, "mako" is assumed. + +bundles + A text file containing a list of files to be turned into bundles using WebAssets. + For example:: + + assets/css/all.css=bootstrap.css,bootstrap-responsive.css,rst.css,code.css,colorbox.css,custom.css + + This creates a file called "assets/css/all.css" in your output that is the + combination of all the other file paths, relative to the output file. + This makes the page much more efficient because it avoids multiple connections to the server, + at the cost of some extra difficult debugging. + + WebAssets supports bundling CSS and JS files. + + Templates should use either the bundle or the individual files based on the ``use_bundles`` + variable, which in turn is set by the ``USE_BUNDLES`` option. + +Creating a New Theme +-------------------- + +In your site's folder, create a ``themes`` folder. Choose a theme to start from, and +create ``themes/yourthemename/parent`` as a file containing the parent theme's name. +There, you just created a new theme. Of course it looks exactly like the other one, +so let's customize it. + +Templates +--------- + +In templates there is a number of files whose name ends in ``.tmpl``. Those are the +theme's page templates. They are done usig the `Mako <http://makotemplates.org>`_ +template language. If you want to do a theme, you should learn the Mako syntax first. + +Mako has a nifty concept of template inheritance. That means that, a +template can inherit from another and only change small bits of the output. For example, +``base.tmpl`` defines the whole layout for a page but has only a placeholder for content +so ``post.tmpl`` only define the content, and the layout is inherited from ``base.tmpl``. + +These are the templates that come with the included themes: + +base.tmpl + This template defines the basic page layout for the site. It's mostly plain HTML + but defines a few blocks that can be re-defined by inheriting templates: + + * ``extra_head`` is a block that is added before ``</head>``, (ex: for adding extra CSS) + * ``belowtitle`` is used by default to display a list of translations but you can put + anything there. + * ``content`` is where the inheriting templates will place the main content of the page. + * ``permalink`` is an absolute path to the page (ex: "/archive/index.html") + + This template always receives the following variables you can use: + + * ``lang`` is the laguage for this page. + * ``title`` is the page's title. + * ``description`` is the page's description. + * ``blog_title`` is the blog's title. + * ``blog_author`` is the blog's author. + * ``messages`` contains the theme's strings and translations. + * ``_link`` is an utility function to create links to other pages in the site. + It takes three arguments, kind, name, lang: + + kind is one of: + + * tag_index (name is ignored) + * tag (and name is the tag name) + * tag_rss (name is the tag name) + * archive (and name is the year, or None for the main archive index) + * index (name is the number in index-number) + * rss (name is ignored) + * gallery (name is the gallery name) + + The returned value is always an absolute path, like "/archive/index.html". + + * ``rel_link`` converts absolute paths to relative ones. You can use it with + ``_link`` and ``permalink`` to create relative links, which makes the site + able to work when moved inside the server. Example: ``rel_link(permalink, url)`` + + * Anything you put in your ``GLOBAL_CONTEXT`` option in ``dodo.py``. This + usually includes ``sidebar_links``, ``search_form``, and others. + + The included themes use at least these: + + * ``rss_link`` a link to custom RSS feed, although it may be empty) + * ``blog_url`` the URL for your site + * ``blog_title`` the name of your site + * ``content_footer`` things like copyright notices, disclaimers, etc. + * ``license`` a larger license badge + * ``analytics`` google scripts, or any JS you want to tack at the end of the body + of the page. + * ``disqus_forum``: a `Disqus <http://disqus.com>`_ ID you can use to enable comments. + + It's probably a bad idea to do a theme that *requires* more than this (please put + a ``README`` in it saying what the user should add in its ``dodo.py``), but there is no + problem in requiring less. + +post.tmpl + Template used for blog posts. Can use everything ``base.tmpl`` uses, plus: + + * ``post``: a Post object. This has a number of members: + + * ``post.title(language)``: returns a localized title + * ``post.date`` + * ``post.tags``: A list of tags + * ``post.text(language)``: the translated text of the post + * ``post.permalink(language, absolute)``: Link to the post in that language. + If ``absolute`` is ``True`` the link contains the full URL. This is useful + for things like Disqus comment forms. + * ``post.next_post`` is None or a Post object that is next newest in the timeline. + * ``post.prev_post`` is None or a Post object that is next oldest in the timeline. + +story.tmpl + Used for pages that are not part of a blog, usually a cleaner, less + intrusive layout than ``post.tmpl``, but same parameters. + +gallery.tmpl + Template used for image galleries. Can use everything ``base.tmpl`` uses, plus: + + * ``text``: A descriptive text for the gallery. + * ``images``: A list of (thumbnail, image) paths. + +index.tmpl + Template used to render the multipost indexes. Can use everything ``base.tmpl`` uses, plus: + + * ``posts``: a list of Post objects, as described above. + * ``prevlink``: a link to a previous page + * ``nextlink``: a link to the next page + +list.tmpl + Template used to display generic lists of links. Can use everything ``base.tmpl`` uses, plus: + + * ``items``: a list of (text, link) elements. + +You can add other templates for specific pages, which the user can the use in his ``post_pages`` +option in ``dodo.py``. Also, keep in mind that your theme is yours, there is no reason why +you would need to maintain the inheritance as it is, or not require whatever data you want. + +Messages and Translations +------------------------- + +When you modify templates, you may want to add text in them (for example: "About Me"). +Instead of adding the text directly, which makes it impossible to translate to other +languages, add it like this:: + + ${messages[lang]["About Me"]} + +Then, in ``messages/en.py`` add it along the other strings:: + + MESSAGES = [ + u"Posts for year %s", + u"Archive", + u"Posts about %s:", + u"Tags", + u"Also available in: ", + u"More posts about", + u"Posted:", + u"Original site", + u"Read in english", + u"About Me", + ] + +Then, when I want to use your theme in spanish, all I have to do is add a line in ``messages/es.py``:: + + MESSAGES = { + u"LANGUAGE": u"Español", + u"Posts for year %s": u"Posts del año %s", + u"Archive": u"Archivo", + u"Posts about %s:": u"Posts sobre %s", + u"Tags": u"Tags", + u"Also available in: ": u"También disponible en: ", + u"More posts about": u"Más posts sobre", + u"Posted:": u"Publicado:", + u"Original site": u"Sitio original", + u"Read in english": u"Leer en español", + u"About Me": u"Acerca del autor", + } + +And voilá, your theme works in spanish. Don't remove strings from these files even if it seems +your theme is not using them. Some are used internally in Nikola to generate titles and +similar things. + +To create a new translation, just copy one of the existing ones, translate the right side of +every string to your language, save it and send it to me, I will add it to Nikola! + |
