There are basically 3 steps:

  • get a local copy of the sources;
  • make you changes, render and check;
  • once ready, submit to the maintainers.

Note: The minimal required tool sets for the recommended way are Git, a text editor, a Github account (free). However, only a text editor is strictly required. ,-)

Get a local copy of the sources

Cloning via the script in ‘offlineimap.git’

This will clone the repository of the sources and do a bit of extra configuration.

$ ./scripts/get-repository.sh website
$ cd ./website
Without OfflineIMAP’s Git repository

If you don’t have the offlineimap Git sources, you can download the script:

$ wget 'https://raw.githubusercontent.com/OfflineIMAP/offlineimap/next/scripts/get-repository.sh'-O get-repository.sh
$ ./scripts/get-repository.sh website

Note: If you downloaded the script via wget, you’ll have to configure the username variable in the renderer file ./run_server.sh.

Cloning with Git

$ git clone https://github.com/OfflineIMAP/offlineimap.github.io.git

From zip source

$ wget 'https://github.com/OfflineIMAP/offlineimap.github.io/archive/master.zip' -O offlineimap-website.zip
$ unzip offlineimap-website.zip

Editing online

Login to Github, browse the sources online in your fork, pick up a file, edit and commit.

What to do next

Make your changes, check how it looks, and submit them to the maintainers, as for usual patches.

Create a blog post

$ cd \_posts
$ ls
$ cp YYYY-MM-DD-whatever.md YYY-MM-DD-my-post.md
<edit>
$ git add .
$ git commit

Then, render it, check, push to your Github fork and make a pull request. If you don’t have a public Git repository, you can send the file of your post to the maintainers.

Create a documentation page

$ cd \_doc
$ ls
$ cp any.md new-doc.md
<edit>
$ git add .
$ git commit

Contrary to the blog posts, pages in _doc are not indexed automaticaly. Edit documentation.html and add a new entry to your documentation page.

Be care that you have to set the URL as a target which ends with .html. Not the source with the .md extension.

Then, render it, check and submit.

Rendering my changes

There are two ways for rendering your changes before submitting them:

Using Github, via your public fork of the offlineimap.git project.

$ ./render.sh

Locally

For rendering it locally, you must have jekyll installed.

$ ./run_server.sh

Submit to the maintainers

With Git

Push your changes to your public fork and request a pull.

Without Git

Put the files you changed as a Gist and request the maintainers. Gists are usefull but not required, if you don’t like it use something else.

Requesting the maintainers the way you’d like:

  • open an issue;
  • send a mail.

About Jekyll

Check out the Jekyll docs for more info on how to get the most out of Jekyll. Bug and feature requests for Jekyll are at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll’s dedicated Help repository.

The syntax

The source files use .md extension for the kramdown syntax which is derivated from mardkown.

The theme

The look is very important. Feel free to add your own touch! We started from the base Jekyll theme because it’s clean and simple.

You can get inspiration from other’s customized themes.

Highlighting

Highlight is made by Jekyll with pygments.

Other ressources