Getting Started with Hyde

Why HYDE

It saves a lot of considerable amount of time rather writing from the scratch. It’s built-in features and plug-ins inspired me to work with it. After satisfying the requirements for the HYDE environment to be set up, it’s hardly a matter of few seconds to have a full-structured working site on your local web server. You’ll greatly appreciate the amount of time spent in serving up when you’ll read about integrating your work with Fabric below, that even these few seconds can be reduced to merely a second, Yep! just a single command to have your website cum blog serving up. Isn’t it interesting? Yeah, Carry on!

Installation and Setup

using python-pip for installing

pip install hyde

Creating a new hyde website (default layout for site)

hyde -s $PATH_TO_DIRECTORY create
# or
cd 'PATH_TO_DIRECTORY' # change to dir
hyde create               # and create default layout
 
# if you switch to created/cw directory, following subdirectories would be created.
ls
content  info.yaml  layout  README.markdown  site.yaml

Generating Site

After editing and modifying the layout, site is generated

hyde gen  # will create a folder named 'deploy' inside current dir

Serve the site Finally start the built in web server that also regenerates based on the request if there are changes.

hyde serve

Publish the site Publishes the site based on configuration. Currently the only supported publishing target is a git repository.

hyde publish -p github

publisher:
    github:
        type: hyde.ext.publishers.dvcs.Git
        path: ../hyde.github.com
        url: git@github.com:hyde/hyde.github.com.git

The above steps i.e removing deploy dir, generating and serving can be combined under one hood, using python awesome library fabric. It’s a command-line tool and it provides a basic suite of operations for executing local or remote shell commands (normally or via sudo) and uploading/downloading files.

Not many people enjoy executing a series of line-by-line commands, which they require frequently. Fabric is thus, very useful when you have to execute a series of commands, without waiting to run next upon completion of former.

#!/usr/bin
# fabfile.py
 
from fabric.api import *
import fabric.contrib.project as project
 
def clean():
  local('rm -rf ./deploy')
 
def gen():
  clean()
  local('hyde gen')
 
def serve():
  local('hyde serve')
 
def cgs():
  gen()
  serve()

fab clean # removes the deploy dir build during generation
fab cgs   # cleaning, re-generating and serving

YAML

YAML: YAML Ain’t Markup Language

What It Is: YAML is a human friendly data serialization standard for all programming languages. It is used for configuration files. HYDE provides control of how templates are applied, using YAML for configuration settings.

site.yaml indicates how some local file directories are translated to paths for the web server, specifies plug-ins to be used like ‘meta.TaggerPlugin‘, ‘text.SyntextPlugin‘, etc. and provides basic metadata.

Markdown

HYDE builds in a processor that allows you to author web pages in Markdown rather than HTML. Markdown is a lightweight markup language, which helps in avoiding hand-authoring HTML, and edit just plain text using special characters to indicate the various HTML markup constructs, and finally converts that plain text formatting to HTML.

Since this was my first experience creating website, i found Markdown simply awsesome to learn and use. It reduces my lots of HTML-coding efforts and helps me writing my blog-posts similar to the way i usually wrote an essay in school :)

I won’t be undertaking an introduction to Markdown, but can provide a simple example to grab on it.

Intro
=====
Section 1
---------
The **dream** is not *what you see in sleep*,
 
**dream** is the thing which does not __let you sleep__.
 
--[Anonymous](#)
 
##Three simple steps to succeed
1. Knowledge
2. Determination
3. The Means

will be converted to :

<h1>Intro</h1>
 
<h2>Section 1</h2>
 
<p>The <strong>dream</strong> is not <em>what you see in sleep</em>,</p>
 
<p><strong>dream</strong> is the thing which does not <strong>let you sleep</strong>.</p>
 
<p>--<a href="#">Anonymous</a></p>
 
<h2>Three simple steps to succeed</h2>
 
<ol>
  <li>Knowledge</li>
  <li>Determination</li>
  <li>The Means</li>
</ol>

You can try it out online Dingus

HYDE Syntax Highlighting Plugin

Ah, HYDE’s built-in plugin Pygments and syntax tag for Syntax Highlighting is just beautiful. It not only makes the code readable but also push colourful pixels to your site. Put the following code along with your Markdown code (as discussed above) to enjoy the Syntax Highlighting for several programming languages.

Replace ‘lang_name’ in the code below with the programming language in order to highlight its syntax. For eg- css, HTML, python, etc. Here lang_name corresponds to python.

{% syntax lang_name %}
  def main():
    print("Hello World!");
{% endsyntax %}

Templates and Jinja2

A template is simply a text file. It can generate any text-based format (HTML, XML, CSV, etc.).

A template contains variables, which get replaced with values when the template is evaluated, and tags, which control the logic of the template.

Jinja2 is a modern and designer friendly templating language for Python, modelled after Django’s templates. It is fast, widely used and secure with the optional sandboxed template execution environment.

The templates go in the layout directory, and you add and update templates there to manipulate the overall content outline of your site.

Below is a minimal template that illustrates a few basics.

<html>
<head>
  {% block head %}
      <link rel="stylesheet" href={{ media_url('css/site.css') }}>
      {% block title %}{{ section.title }}{% endblock %}
  {% endblock %}
</head>
<body>
  <ul id="navigation">
     {% for item in navigation %}
          <li><a href="{item.href}">{{item.caption}}</a></li>
     {% endfor %}
  </ul>
 
  {% block content %}
    {{ super() }} # inheriting from parent/base
  {% endblock content %}
 

  {% block footer %}
      &copy; Copyright 2008 by <a href="http://domain.invalid/">you</a>.
  {% endblock footer %}
 
</body>
</html>

Full documentation can be found on Jinja2 Docs

I found this template engine quite interesting to use. A template allows to express most of the replicated entries in each HTML page only once, which is often called as base template of the whole site, and is automatically applied to all the pages which inherit them, often called as child template.

Layout

Content

This is the directory where static files such as images, stylsheets and script-files are stored in order to serve the site. This folder is the foundation for providing the structure to the site. HTML page files starts with the page metadata and then inherit the code (as stored in jinja files with .j2 ext ) from the layout directory.