Getting my website up and running with Urubu took me longer than it needed to. Here are a few pointers to make your work a little bit easier.

You've gone through the Urubu Quickstart, probably even read a few pages of the documentation. You've downloaded your own copy of the Quickstart. And now you're ready and rarin' to get started building your own website.

"Whoah," this page is saying. "Sure, you gotta make hay while the sun shines, but hold your horses a little first. Don't be putting the ox before the cart. Close the barn door behind you. Haste makes waste."

That last injunction is the most important. In creating Close to the Machine, I set myself straight to work with new pages and content. Only later did I realize I should have begun with a few simple tasks which I describe on this page.

Experienced website developers may not find this useful. It was written with beginners in mind. People like myself when I started migrating my website to Urubu.

First Steps Checklist

Clean up the Template Pages

You'll find the template pages in the _layouts directory in Urubu Quickstart.

  • Redo the indentation. I could be wrong, but there doesn't seem to be a widely-accepted standard for template indentation. The Urubu Quickstart pages use two space. I prefer four, but I could live with two. What bothers me more about the Urubu Quickstart is the internal indentation of the Jinja tags, by which I mean the spacing between the "%" and the first letter of the Jinja command in the following snippet.
    {% for item in site.reflinks['/'].content[:navbar_right_index] %}
    {%   set context = '' %}
    {%   if item.components|d and this.components[0] == item.components[0] %}
    {%     set context = ' class="active"' %}
    {%   endif %}
    {%   if item.content|d and item.dropdown %}
    [...]
    {%   endif %}
    {% endfor %}
  • Redo the endblock tags. Replace {% endblock %} with {% endblock <blockname> %}. Like good indentation, this helps the developer make sense of what is happening on the page.

As an illustration of these two points, the next two code blocks show the Urubu code before and after the changes I suggest.

In Urubu Quickstart, _base.html has the following.

  <ul class="nav navbar-nav navbar-left">
    {% block home %}
    {% endblock %}
    {% for item in site.reflinks['/'].content[:navbar_right_index] %}
    {%   set context = '' %}
    {%   if item.components|d and this.components[0] == item.components[0] %}
    {%     set context = ' class="active"' %}
    {%   endif %}
    {%   if item.content|d and item.dropdown %}
    <li{{context}} class="dropdown">
      <a href="{{item.url}}" class="dropdown-toggle" data-toggle="dropdown">{{item.title}} <b class="caret"></b></a>
      <ul class="dropdown-menu">
        {% for subitem in item.content %}
        <li><a href="{{subitem.url}}">{{subitem.title}}</a></li>
        {% endfor %}
      </ul>
    </li>
    {% else %}
    <li{{context}}><a href="{{item.url}}">{{item.title}}</a></li>
    {%   endif %}
    {% endfor %}
  </ul>

With the modifications described above, this snippet now looks like this.

    <ul class="nav navbar-nav navbar-left">
        {% block home %}
        {% endblock home %}
        {% for item in site.reflinks['/'].content[:navbar_right_index] %}
            {% set context = '' %}
            {% if item.components|d and this.components[0] == item.components[0] %}
                {% set context = ' class="active"' %}
            {% endif %}
            {% if item.content|d and item.dropdown %}
                <li{{context}} class="dropdown">
                    <a href="{{item.url}}" class="dropdown-toggle" data-toggle="dropdown">{{item.title}} <b class="caret"></b></a>
                    <ul class="dropdown-menu">
                        {% for subitem in item.content %}
                            <li><a href="{{subitem.url}}">{{subitem.title}}</a></li>
                        {% endfor %}
                    </ul>
                </li>
            {% else %}
                <li{{context}}><a href="{{item.url}}">{{item.title}}</a></li>
            {% endif %}
        {% endfor %}
    </ul>

The usefulness of replacing {% endblock %} with {% endblock <blockname> %} isn't terribly clear in this example. It's far more obvious when there is code between the start- and end-block segments.

Separate Your Code from the Original

You'll build your website by starting with the Urubu Quickstart project that you download, then making one change at a time. You'll change the layout, replace existing content with your own, add new pages, and so on. Inevitably you're going to run into problems. Something won't scroll properly; your page won't resize elegantly; the table of contents or the breadcrumbs won't display correctly. You're going to want to know whether you introduced the problem yourself, or if the problem exists in the Urubu Quickstart project. These two tips will help you quickly determine how you ended up wherever you happen to be.

  • Download two copies of the Quickstart project. The first copy will be the starting point of your project. This is the copy you'll modify. The second copy should be tucked away someplace where you won't lose it. This is what you'll refer to, or run, in order to compare your website's behavior to the original's.

  • Start a separate .css file for your own modifications. Since CSS files are cascading style sheets, new styling overrides old styling. You don't need to change Quickstart's styling; just do your own styling afterward. In this way you'll be able to comment out your own work to see how the original version of the project behaves.

    • How to do this? Easy. Create your own file—let's call it custom.css—and put it in the css directory in the project. Then add your new file in layouts/_base.html immediately after the other .css files, like so:
{% set url_prefix = '' %}
{% if site.baseurl %}
{%   set url_prefix = '/' + site.baseurl %}
{% endif %}
<link href="{{url_prefix + '/css/site.css'}}" rel="stylesheet" media="screen">
<link href="{{url_prefix + '/css/syntax.css'}}" rel="stylesheet" media="screen">
<link href="{{url_prefix + '/css/custom.css'}}" rel="stylesheet" media="screen">

The Jumbotron Banner

  • The Jumbotron. No doubt about it, you'll want to improve on the default jumbotron. (See Parts of an Urubu Home Page if you're not sure what we're talking about here.) No doubt Jan Decaluwe decided not to put too much effort into the Quickstart version, since it would be one of the first things new users would undo. Now that you've done the tasks already listed above—in particular, created your own .css file and cleaned up the .html pages—feel free to get started. But if you're a newbie like myself, be aware that it will probably take a good deal of time...

  • Put the jumbotron banner on every page. I'm not sure why each page of the Quickstart project doesn't share the same header or banner. It's my impression that most websites do. In my opinion, the shared content improves the user experience. At the very least, it makes clear to your users when they have clicked off a link and navigated to a different website.

    • You put the jumbotron banner on every page of your website by moving its HTML out of _layouts/home.html and _layouts/index.html, then putting it into the correct location in _base.html. Instead of using the value of title from the current markdown page, you will probably want to use the value of brand in _site.yml. After the move, the relevant lines from _base.html will look like the example below. (Of course, if you've already modified the jumbotron, the contents of the jumbotron div will look different from the default contents given here.) 
<div class="jumbotron">
  <div class="container text-center">
    <div class="row">
      <div class="col-md-8 col-md-offset-2">
            {% if site.brand %}
                <h1>{{site.brand}}</h1>
            {% else %}
                <h1>{{this.title}}</h1>
            {% endif %}
      </div>
   </div>
 </div>
</div>

{% block body %}
{% endblock body %}

Other Important Tasks

  • Put content on your home page. In most cases, you'll want some content on your home page rather than just a button. Because Urubu relies on Bootstrap, you have to wrap the content in containers so that it is displayed correctly. The code below shows how your layouts/home.html might look to accomplish this. The code refers to this.body, which is the content of the top-level index.md markdown file. This is empty in the default Urubu Quickstart project, so you'll need to add something to that file for the contents to appear on your home page.
<!-- For index.html in top folder only. -->
{% extends "_base.html" %}

{% block home %}
{% endblock home %}

{% block body %}
    <div class="container text-center">
      <a class="btn btn-primary btn-lg" href="start.html">Start</a>
    </div>

    <div class="container">
        <div class="row">
            {% block content %}
                <div class="col-md-7 content" role="main">
                    <main>
                        {{this.body}}
                    </main>
                </div>
            {% endblock content %}
        </div>
        {% include 'footer.html' %}
    </div>
{% endblock body %}

  • Learn how to use developer tools in your browser. In Firefox, it's Tools > Web Developer > Inspector. In Safari, Develop > Show Web Inspector (though I have a dim memory that I might have downloaded something to get the Developer dropdown to appear in Safari). Whatever your browser, there's a way to see the HTML and CSS behind the presentation. Learn how to navigate the browser's developer tools. Especially, figure out how to modify the CSS with the click of a button or a change in a property.

  • Learn and be aware of the possibilities that filters provide you. Whenever you find your efforts stymied, consider the use of filters as a solution. In a filter you get to use Python code. A lot can be accomplished with a little Python code. See Build Your Own Sidebar for an example.

Another, Still Important, Task

  • Read the Urubu documentation. This is this section's only task, and even though it's a little less important than the other tasks, your website will be all the better if you follow this piece of advice. Go through the excellent documentation in the Urubu Manual. Check out the issues page. Then go through the manual one more time.

Typographic Style Guidelines

By typographic style, I'm referring to when you use elements like boldface, italics, double quotes and the <code> tag. You could simply use whatever element feels right at the moment. That's certainly a legitimate approach. On the other hand, if you want your website to look professional, then sooner rather than later you should think about being consistent, and to be consistent you'll need some kind of style guidelines that you can easily refer to.

On a separate page I have posted my own style guide. (It may take some time for me to update my website so that it follows these guidelines.) Feel free to borrow from it for yourself, or to have a look at the pages in the references section for some other input.

Special HTML Tags

One decision that took me a long time to make was whether, and when, to use special HTML tags like <kbd> and <var>. To speed things up for you, in this section I give you some HTML and markup that will let you quickly compare how these tags appear in a browser with whatever CSS styling you are working with.

Use these HTML snippets to test how these tags appear in your browser.

<code>This is a test using the `<code>` tag. </code> 

<mark>This is a test using the `<mark>` tag. </mark> 

<samp>This is a test using the `<samp>` tag. </samp> 

<kbd>This is a test using the `<kbd>` tag. </kbd> 

<var>This is a test using the `<var>` tag. </var> 

<strong>This is a test using the `<strong>` tag. </strong>  

<em>This is a test using the `<em>` tag. </em>

Use these markdown snippets to see how your website generator deals with conventional ways of formatting text:

*This markdown paragraph is surrounded by a single asterisk.*

**This markdown paragraph is surrounded by two asterisks.**

_This markdown paragraph is surrounded by an underscore._

Here's how these work with my website generator and CSS styles in the browser you're using to read this page:

This is a test using the <code> tag.

This is a test using the <mark> tag.

This is a test using the <samp> tag.

This is a test using the <kbd> tag.

This is a test using the <var> tag.

This is a test using the <strong> tag.

This is a test using the <em> tag.

This markdown paragraph is surrounded by a single asterisk.

This markdown paragraph is surrounded by two asterisks.

This markdown paragraph is surrounded by an underscore.