For these pages, and the problems I had making the migration, to make sense, you should probably have a little background info.

My Programming Background

Although a professional software engineer, I didn't know much about web development when I began using Urubu. I can read the Urubu Quickstart Guide with ease, but there are a number of topics in the Manual that I can't follow at all—the manual assumes knowledge I don't have.

These pages on Urubu in Close to the Machine may also, oblivious to me, assume knowledge on your part. Knowing what I knew at the start of this migration should, I think, help the reader make sense of these pages. If you can't follow what I'm saying, it could be the fault of bad writing, true—but it could also be assuming knowledge you don't have.

The closer your knowledge is to my knowledge at the start of this project, the more you'll understand what I'm trying to say, and the more my Urubu problems will anticipate the kinds of problems you'll encounter in your own Urubu project.

What I knew:

  • How to write good code in a number of languages, including Python
  • How to architect a complex software project
  • How to build and maintain a website in HTML and CSS
  • IDEs such as Eclipse, IntelliJ IDEA and PyCharm
  • SQL, Subversion, etc

What I knew a little of:

  • One flavor of markdown for a particular company's wiki
  • Git
  • Writing iOS apps in Xcode
  • pyenv
  • Using the Inspector tool in Firefox

What I knew practically nothing about:

  • General web development
  • Real markdown
  • Jinja or Jinja2, or template engines in general
  • JavaScript
  • Bootstrap
  • Contributing to an open source project

My Approach to the Migration

I decided to perform this migration as much as possible without access to the Python code which Urubu is built upon. After all, Jan Decaluwe designed Urubu to be used in this way--and for the time being I want to remain as true to that spirit as I can.

But there's another reason this approach is a good one. I have enough to learn already (see "What I knew practically nothing about," above). It doesn't make sense for me to make my learning curve even steeper.

The point is that, when I describe, in these pages, a problem I encountered, my approach to the solution of the problem is likely to be very different from the approach of a contributor to the Urubu open source project. A contributor has the option of stepping through the Python code, seeing exactly what is going on during the build process. As a mere user of the Urubu website generator, however, I don't have that option. I have to use other means to understand why something isn't working. And I may have to satisfy myself with finding a work-around to the problem without ever fully understanding why my original approach didn't work.

It is possible that one day I'll get the Python code and become a contributor. But that's not how I started this migration, and you need to know that to make sense of these pages.