From 3a0d66f07b112b6d2bdc2b57bbf717a89a351ce6 Mon Sep 17 00:00:00 2001 From: Unit 193 Date: Wed, 3 Feb 2021 19:17:00 -0500 Subject: New upstream version 8.1.2. --- docs/creating-a-theme.rst | 851 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 851 insertions(+) create mode 100644 docs/creating-a-theme.rst (limited to 'docs/creating-a-theme.rst') diff --git a/docs/creating-a-theme.rst b/docs/creating-a-theme.rst new file mode 100644 index 0000000..a1b737d --- /dev/null +++ b/docs/creating-a-theme.rst @@ -0,0 +1,851 @@ +.. title: Creating a Theme +.. slug: creating-a-theme +.. date: 2015-05-28 18:46:48 UTC +.. tags: +.. category: +.. link: +.. description: +.. type: text + +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 :doc:`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_base.css`` and ``assets/css/code.css`` to function properly. +We will also add themes for Jupyter (``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. +There’s also ``assets/css/nikola_rst.css``, which adds Bootstrap 3-style reST notes etc. + +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 +
+