.. slug: creating-a-theme .. date: 2015-05-28 18:46:48 UTC .. tags: .. category: .. link: .. description: .. type: text Creating a Theme ================ 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. 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. If you are looking for a reference, check out `Theming reference `_ and `Template variables `_. Today’s theme is `Lanyon `__ which is written by `@mdo `__ and released under a MIT license, which is liberal enough. So, let’s get started. Checking It Out --------------- 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! So:: # Get jekyll sudo apt-get install jekyll # Get Lanyon git clone git@github.com:poole/lanyon.git # 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.8.0. 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`` as a parent and ``jinja`` as engine instead:: $ cd lanyon-port/ $ nikola theme -n lanyon --parent base --engine mako Edit ``conf.py`` and set ``THEME = 'lanyon'``. Also set ``USE_BUNDLES = False`` (just do it for now, we’ll get to bundles later). Also, if you intend to publish your theme on the Index, or want to use it with older versions (v7.8.5 or older), use the ``--legacy-meta`` option for ``nikola theme -n``. You can now build that site using ``nikola build`` and it will look like this: .. figure:: https://getnikola.com/images/lanyon-0.thumbnail.png :target: https://getnikola.com/images/lanyon-0.png This is just the base theme. Basic CSS --------- 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: .. code:: html 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 My Nikola Site | My Nikola Site 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, make a copy in your theme (note this command requires setting your ``THEME`` in ``conf.py`` to ``lanyon``):: $ nikola theme -c 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 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