From b0b24795b24ee6809397fbbadf42f31f310a219f Mon Sep 17 00:00:00 2001 From: Agustin Henze Date: Wed, 8 Jul 2015 07:35:02 -0300 Subject: Imported Upstream version 7.6.0 --- docs/creating-a-theme.txt | 1033 ++++++++++++++++++++++++++++++++------------- 1 file changed, 739 insertions(+), 294 deletions(-) (limited to 'docs/creating-a-theme.txt') diff --git a/docs/creating-a-theme.txt b/docs/creating-a-theme.txt index 220a8e7..7113b1a 100644 --- a/docs/creating-a-theme.txt +++ b/docs/creating-a-theme.txt @@ -1,380 +1,825 @@ -.. title: Creating a Theme +.. title: Creating A Theme .. slug: creating-a-theme -.. date: 2012-03-13 12:00:00 UTC-03:00 +.. date: 2015-05-28 18:46:48 UTC .. tags: +.. category: .. link: .. description: +.. type: text -Creating A Theme From Scratch (Almost) -====================================== +Nikola is a static site and blog generator. So is Jekyll. While I like what we have done with Nikola, +I do admit that Jekyll (and others!) have many more, and nicer themes than Nikola does. -.. class:: lead +This document is an attempt at making it easier for 3rd parties (that means *you* people! ;-) to +create themes. Since I **suck** at designing websites, I asked for opinions on themes to port, +and got some feedback. Since this is **Not So Hard™**, I will try to make time to port a few +and see what happens. -There is some documentation about creating themes for Nikola, but maybe a tutorial is also a useful way -to explain it. So, here it is. I'll explain how to create a theme (almost) from scratch. All themes -in Nikola must inherit from the ``base`` theme. In this case, we will inherit from ``bootstrap`` -so we get good support for slides and galleries. +Today’s theme is `Lanyon `__ which is written by `@mdo `__ +and released under a MIT license, which is liberal enough. -I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme `_. +So, let’s get started. -.. TEASER_END +Checking It Out +--------------- -Starting The Theme ------------------- +The first step in porting a theme is making the original theme work. Lanyon is awesome in that its +`GitHub project `__ is a full site! -First we will create a testing site:: +So:: - $ nikola init --demo monospace-site - A new site with some sample data has been created at monospace-site. - See README.txt in that folder for more information. + # Get jekyll + sudo apt-get install jekyll - $ cd monospace-site/ + # Get Lanyon + git clone git@github.com:poole/lanyon.git -Our theme will inherit from the ``bootstrap`` theme, which is full-featured but boring. + # Build it + cd lanyon && jekyll build -:: + # Look at it + jekyll serve & google-chrome http://localhost:4000 +If you **do not want to install Jekyll**, you can also see it in action at http://lanyon.getpoole.com/ + +Some things jump to my mind: + +1. This is one fine looking theme +2. Very clear and readable +3. Nice hidden navigation-thingy + +Also, from looking at `the project’s README `__ +it supports some nice configuration options: + +1. Color schemes +2. Reverse layout +3. Sidebar overlay instead of push +4. Open the sidebar by default, or on a per-page basis by using its metadata + +Let’s try to make all those nice things survive the porting. + +Starting From Somewhere +----------------------- + +Nikola has a nice, clean, base theme from which you can start when writing your own theme. +Why start from that instead of from a clean slate? Because theme inheritance is going to save you a ton of work, +that’s why. If you start from scratch you won’t be able to build **anything** until you have a bunch of +templates written. Starting from base, you just need to hack on the things you **need** to change. + +First, we create a site with some content in it. We’ll use the ``nikola init`` wizard (with the ``--demo`` option) for that:: + + $ nikola init --demo lanyon-port + Creating Nikola Site + ==================== + + This is Nikola v7.4.1. We will now ask you a few easy questions about your new site. + If you do not want to answer and want to go with the defaults instead, simply restart with the `-q` parameter. + --- Questions about the site --- + Site title [My Nikola Site]: + Site author [Nikola Tesla]: + Site author's e-mail [n.tesla@example.com]: + Site description [This is a demo site for Nikola.]: + Site URL [https://example.com/]: + --- Questions about languages and locales --- + We will now ask you to provide the list of languages you want to use. + Please list all the desired languages, comma-separated, using ISO 639-1 codes. The first language will be used as the default. + Type '?' (a question mark, sans quotes) to list available languages. + Language(s) to use [en]: + + Please choose the correct time zone for your blog. Nikola uses the tz database. + You can find your time zone here: + http://en.wikipedia.org/wiki/List_of_tz_database_time_zones + + Time zone [UTC]: + Current time in UTC: 16:02:07 + Use this time zone? [Y/n] + --- Questions about comments --- + You can configure comments now. Type '?' (a question mark, sans quotes) to list available comment systems. If you do not want any comments, just leave the field blank. + Comment system: + + That's it, Nikola is now configured. Make sure to edit conf.py to your liking. + If you are looking for themes and addons, check out https://themes.getnikola.com/ and https://plugins.getnikola.com/. + Have fun! + [2015-05-28T16:02:08Z] INFO: init: A new site with example data has been created at lanyon-port. + [2015-05-28T16:02:08Z] INFO: init: See README.txt in that folder for more information. + + +Then, we create an empty theme inheriting from base. This theme will use Mako templates. If you prefer Jinja2, +then you should use ``base-jinja`` instead:: + + $ cd lanyon-port/ $ mkdir themes - $ mkdir themes/monospace - $ echo bootstrap > themes/monospace/parent + $ mkdir themes/lanyon + $ echo base > themes/lanyon/parent -The next step is to make the testing site use this new theme, by editing ``conf.py`` and -changing the ``THEME`` option:: +Edit ``conf.py`` and set ``THEME = 'lanyon'``. Also set ``USE_BUNDLES = False`` (just do it for now, we’ll get to bundles later). - # Name of the theme to use. Themes are located in themes/theme_name - THEME = 'monospace' +You can now build that site using ``nikola build`` and it will look like this: -Now we can already build and test the site:: +.. figure:: https://getnikola.com/images/lanyon-0.thumbnail.png + :target: https://getnikola.com/images/lanyon-0.png - $ nikola build && nikola serve + This is just the base theme. -.. figure:: http://ralsina.com.ar/galleries/monospace-tut/monospace-1.png - :height: 400px +Basic CSS +--------- - This is the default "bootstrap" theme. +The next step is to know exactly how Lanyon’s pages work. To do this, we read its HTML. +First let’s look at the head element: -Of course, the page layout is completely different from what we want. To fix that, we need to -get into templates. +.. code:: html -Templates: Page Layout ----------------------- + + -The general page layout for the theme is done by the ``base.tmpl`` template, which is done using -`Mako `_. This is bootstrap's ``base.tmpl``, it's not very big: + + + -.. code-block:: mako + + + + + Lanyon · A Jekyll theme + + + + + + + + + + + + + + + + + [...] + + +The interesting part there is that it loads a few CSS files. If you check the source of your Nikola site, you will +see something fairly similar: + +.. code:: html - ## -*- coding: utf-8 -*- - <%namespace name="base" file="base_helper.tmpl" import="*" /> - <%namespace name="bootstrap" file="bootstrap_helper.tmpl" import="*" /> - ${set_locale(lang)} - + - - ${bootstrap.html_head()} - <%block name="extra_head"> - - ${extra_head_data} + + + + My Nikola Site | My Nikola Site + + + + + + + + - - - - -
- -
-
-
- <%block name="content"> -
+ + +Luckily, since this is all under a very liberal license, we can just copy these CSS files into +Nikola, adapting the paths a little so that they follow our conventions:: + + $ mkdir -p themes/lanyon/assets/css + $ cp ../lanyon/public/css/poole.css themes/lanyon/assets/css/ + $ cp ../lanyon/public/css/lanyon.css themes/lanyon/assets/css/ + +Notice I am *not* copying ``syntax.css``? That’s because Nikola handles that styles for syntax highlighting +in a particular way, using a setting called ``CODE_COLOR_SCHEME`` where you can configure +what color scheme the syntax highlighter uses. You can use your own ``assets/css/code.css`` if you +don’t like the provided ones. + +Nikola **requires** ``assets/css/rst.css`` and ``assets/css/code.css`` to function properly. +We will also add themes for IPython Notebook (``assets/css/ipython.min.css`` +and ``assets/css/nikola_ipython.css``) into the template; note that they are +activated only if you configured your ``POSTS``/``PAGES`` with ipynb support. + +But how do I tell **our** lanyon theme to use those CSS files instead of whatever it’s using now? +By giving our theme its own base_helper.tmpl. + +That file is a **template** used to generate parts of the pages. It’s large and +complicated but we don’t need to change a lot of it. First, get it from +`Nikola’s source code `__ and put a copy in ``themes/lanyon/templates/base_helper.tmpl``:: + + $ mkdir themes/lanyon/templates + $ curl https://raw.githubusercontent.com/getnikola/nikola/master/nikola/data/themes/base/templates/base_helper.tmpl > themes/lanyon/templates/base_helper.tmpl + +The part we want to change is this: + +.. code:: html+mako + + <%def name="html_stylesheets()"> + %if use_bundles: + %if use_cdn: + + %else: + + %endif + %else: + + + + %if has_custom_css: + + %endif + %endif + % if needs_ipython_css: + + + % endif + + +And we will change it so it uses the lanyon styles instead of theme.css (again, ignore the bundles for now!): + +.. code:: html+mako + + <%def name="html_stylesheets()"> + %if use_bundles: + + %else: + + + + + %if has_custom_css: + + %endif + %endif + % if needs_ipython_css: + + + % endif + + + +.. figure:: https://getnikola.com/images/lanyon-1.thumbnail.png + :target: https://getnikola.com/images/lanyon-1.png + + You may say this looks like crap. Don’t worry, we are just starting :-) + +Page Layout +----------- + +This is trickier but should be no problem for people with a basic understanding of HTML and a desire to make a theme! + +Lanyon’s content is split in two parts: a sidebar and the rest. The sidebar looks like this (shortened for comprehension): + +.. code:: html + + + + + + + -
- ${content_footer} + +
- ${bootstrap.late_load_js()} - ${base.html_social()} - - <%block name="extra_js"> - ${body_end} - +So, a plain body, with an input element that controls the sidebar, a div which is the sidebar itself. +Inside that, div.sidebar-item for items, and a nav with "navigational links". This is followed by the "masthead" and +the content itself, which we will look at in a bit. + +If we look for the equivalent code in Nikola’s side, we see this: + +.. code:: html + + + Skip to main content +
+ + + +Customization +------------- + +The original Lanyon theme supports some personalization options. It suggests you do them by tweaking the templates, and +you *can* also do that in the Nikola port. But we prefer to use options for that, so that you can get a later, better +version of the theme and it will still "just work". + +Let’s see the color schemes first. They apply easily, just tweak your ``body`` element like this: + +.. code:: html + + + ... + + +We can tweak ``base.tmpl`` to do just that: + +.. code:: html+mako + + % if lanyon_subtheme: + + %else: + + %endif + +And then we can put the options in conf.py’s ``GLOBAL_CONTEXT``: + +.. code:: python + + GLOBAL_CONTEXT = { + "lanyon_subtheme": "theme-base-08" + } + +.. figure:: https://getnikola.com/images/lanyon-7.thumbnail.png + :target: https://getnikola.com/images/lanyon-7.png + + Look at it, all themed up. + +Doing the same for layout-reverse, sidebar-overlay and the rest is left as an exercise for the reader. + +Bundles +------- + +If you have ``webassets`` installed and the ``USE_BUNDLES`` option set to True, Nikola can put several CSS or JS files together in a larger file, +which makes sites load faster. To do that, your theme needs a ``bundles`` file where the syntax is:: + + outputfile1.js=thing1.js,thing2.js,... + outputfile2.css=thing1.css,thing2.css,... + +For the Lanyon theme, it should be like this:: + assets/css/all.css=rst.css,code.css,poole.css,lanyon.css,custom.css -.. figure:: http://ralsina.com.ar/galleries/monospace-tut/monospace-5.png - :height: 400px +**Note:** Some themes also support the ``USE_CDN`` option meaning that in some cases it will load one bundle with all CSS and in other will load some CSS files +from a CDN and others from a bundle. This is complicated and probably not worth the effort. - Details, details. +The End +------- -The demo site exercises most of the features in Nikola, so if you make it look good, your site probably will look good too. -This monospace theme is included with nikola, if you want to use it or play with it. +And that’s it, that’s a whole theme. Eventually, once people start using it, they will notice small broken details, which will need handling one at a time. +This theme should be available in http://themes.getnikola.com#lanyon and you can see it in action at https://themes.getnikola.com/v7/lanyon/index.html -- cgit v1.2.3