This document is an attempt at making it easier for 3rd parties (that means you people! ;-) to

and got some feedback. Since this is **Not So Hard (TM)** I will try to make time to port a few

Today's theme is `Lanyon <https://github.com/poole/lanyon>`__ which is written by `@mdo <https://twitter.com/mdo>`__

So, let's get started.

`github prohject <https://github.com/poole/lanyon>`__ is a full site!

If you want, you can also see it in action at http://lanyon.getpoole.com/

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 <https://github.com/poole/lanyon/blob/master/README.md>`__

1) color scheme themes

2) reverse layout

3) sidebar overlay instead of push

4) show the sidebar open by default, or based on a page's metadata

Let's try to make all those nice things survive the porting.

that's why. If you start from scratch you won't be able to build **anything** until you have a bunch of

then you should use base-jinja instead::

Edit conf.py and set ``THEME = 'lanyon'``. Also set ``USE_BUNDLES = False`` (just do it for now, we'll get to bundles later).

.. figure:: /images/lanyon-0.thumbnail.png

:target: /images/lanyon-0.png

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:

Nikola, adapting a little the paths so that they follow

our conventions::

Notice I am *not* copying ``syntax.css``? That's because Nikola handles that styles for syntax highlighting

don't like the provided ones.

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 <https://github.com/getnikola/nikola/blob/master/nikola/data/themes/base/templates/base_helper.tmpl>`__ and put a copy in ``themes/lanyon/templates/base_helper.tmpl``::

.. figure:: /images/lanyon-1.thumbnail.png

:target: /images/lanyon-1.png

You may say this looks like crap. Don't worry, we are just starting :-)

Lanyon's content is split in two parts: a sidebar and the rest. The sidebar looks like this (shortened for comprehension):

If we look for the equivalent code in Nikola's side, we see this:

Let's make it lanyon-like! We will need 2 more templates: `base.tmpl <https://github.com/getnikola/nikola/blob/master/nikola/data/themes/base/templates/base.tmpl>`__ and `base_header.tmpl <https://github.com/getnikola/nikola/blob/master/nikola/data/themes/base/templates/base_header.tmpl>`__. Get them and put them in your ``themes/lanyon/templates`` folder.

Let's look at ``base.tmpl`` first. It's short and nice, it looks like a webpage without

.. figure:: /images/lanyon-2.thumbnail.png

:target: /images/lanyon-2.png

And that's after I exposed the sidebar by clicking on an invisible widget!

One problem, which causes that yellow color in the sidebar is a CSS conflict. We are loading rst.css which specifies

the background color of ``div.sidebar`` which is more specific than lanyon.css, which specifies for ``.sidebar`` alone.

**Note: this means this theme will not support submenus in navigation. If you want that, I'll happily take a patch.**

.. figure:: /images/lanyon-3.thumbnail.png

:target: /images/lanyon-3.png

Now let's look at the content. In Lanyon, this is how the "main" content looks:

Everything inside the "container content" div is ... the content. The rest is a masthead with the site title

and at the bottom a label for the sidebar's toggle. Easy to do in ``base.tmpl`` (only showing relevant part):

.. figure:: /images/lanyon-4.thumbnail.png

:target: /images/lanyon-4.png

The sidebar looks bad because of yet more CSS conflicts with rst.css. By adding some extra styling in lanyon.css, it will look better.

div.sidebar,.sidebar {

position: fixed;

top: 0;

bottom: 0;

left: -14rem;

width: 14rem;

visibility: hidden;

overflow-y: auto;

padding: 0;

margin: 0;

border: none;

font-family: "PT Sans", Helvetica, Arial, sans-serif;

font-size: .875rem; /* 15px */

color: rgba(255,255,255,.6);

background-color: #202020;

-webkit-transition: all .3s ease-in-out;

transition: all .3s ease-in-out;

Also, the accessibility link on top is visible when it should not. That's because we removed "theme.css" from the base theme, and with it, we lost a couple of classes. We can add them in lanyon.css, along with others used by other

position: absolute;

width: 1px;

height: 1px;

padding: 0;

margin: -1px;

overflow: hidden;

clip: rect(0, 0, 0, 0);

border: 0;

position: static;

width: auto;

height: auto;

margin: 0;

overflow: visible;

clip: auto;

padding: 8px 15px;

margin-bottom: 20px;

list-style: none;

display: inline-block;

margin-right: 0;

margin-left: 0;

content: ' / ';

color: #888;

content: '';

margin-left: 0;

display: inline-block;

margin-right: 10px;

margin-right: 0;

.. figure:: /images/lanyon-5.thumbnail.png

:target: /images/lanyon-5.png

One clear problem is that the title "Lanyon A Jekyll theme" is set in the theme itself. We don't do that sort of things

in Nikola, we have settings for that. So, let's use it. There is a ``html_site_title`` function in ``base_helper.tmpl`` which is just the thing. So we change base.tmpl to use it:

That's a H1 instead of a H3 like Lanyon does, but hey, it's the right thing to do. If you want to go with an H3, just

And now we more or less have the correct page layout and styles. Except for a rather large thing...

Let's start with the titles. Here's how they look in Lanyon:

As for the actual content, that's not in any of the templates we have seen so far. The page you see is an

"index.tmpl" page, which means it's a list of blog posts shown one below the other. Obviously it's not doing

things in the way the Lanyon CSS expects it to. Here's the original, which you can find in Nikola's source

With these changes, it looks ... similar?

.. figure:: /images/lanyon-6.thumbnail.png

:target: /images/lanyon-6.png

Similar changes (basically adding classnames to elements) needed to be done in ``post_header.tmpl``:

you *can* do that in Nikola's port also. But we prefer to use options for that, so that you can get a later, better

Let's see the color schemes first. They apply easily, just tweak your ``body`` element like this:

And then we can put the options in conf.py's ``GLOBAL_CONTEXT``:

.. figure:: /images/lanyon-7.thumbnail.png

:target: /images/lanyon-7.png

Doing the same for layout-reverse, sidebar-overlay and the rest is left as an excercise for the reader.

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.