Skip to content

Contributing

Jump to bottom
maul-esel edited this page Jan 13, 2012 · 9 revisions

Contributing

You're welcome to contribute to this project. Check out the tips below that will help you to do so successfully. If you have any questions on this document or ahkbook itself, PM me on github or contact me in the AutoHotkey forums.

Note:

This page is for github users. If you want to contribute without using github, just contact me on the AutoHotkey forum (user name: maul.esel).

Setup

  1. Clone the project and fork it on github.

  2. If you have access to a machine or VirtualMachine running Linux (or Ubuntu or whatever), install Jekyll locally there: sudo gem install jekyll. This software is used on github to process your content.

    • free VM software: VirtualBox.
    • You should also install Pygments v1.4+.
    • Make sure you have Liquid v2.2.2 installed, not a newer version as v2.3.0 breaks syntax highlighting.

  3. In case you're going to do any stylesheet modifications, change the url-setting in _config.yml to 'http://[your username].github.com/ahkbook' and commit this change. Doing so allows you to see the page with the correct stylesheets.

    • If you installed Jekyll locally, you may later change the setting to the path to your local clone to enable offline tests. Do not commit this change.

Installing Jekyll locally saves you a lot of commits as you can see the results of your work before commiting. However, it's not required, as your content is automatically processed whenever you push to github. I won't care as long as you don't break github ;-)

Working on ahkbook

Now you can do your changes. You may create as many new branches as you want. Add posts to the index, author missing posts, improve existing ones, add pictures, translate posts in other languages (placing them in the correct subfolder, such as fr/_posts for french), ... You may also add yourself to the list of contributors on the start page, with a website of your choice.

You can write your posts in either HTML, Markdown (preferred) or Textile.

YAML settings

In either case include a YAML front matter section at the top. It should look like this:

---
title: My post
layout: post # this must always be 'post'!
permalink: /en/My-Post.html # correct the language if necessary.
---

If you really need a custom CSS file for a post (generally you shouldn't use one), place it in the /css folder add a css_files setting:

css_files: ['custom-style', 'my-style'] # includes /css/custom-style.css and /css/my-style.css

This applies to HTML as well as to Markdown and Textile.

Where to save posts?

Save the posts as /[your language]/_posts/[year]-[month]-[day]-[title].[markup], for example:

  • /en/_posts/2011-11-05-First-Steps.markdown or
  • /en/_posts/2011-11-05-AutoHotkey-and-COM.textile.

The actual date is currently not used, but Jekyll requires this format. For consistency, use the same "title" here as in the permalink setting in the YAML front matter.

Format

If you're using HTML, only include the body's contents, not the head, the <body> element itself or the <html> element. The content you write is automatically placed in a layout template.

This project uses Maruku as Markdown engine. You may make use of it's extended meta-syntax, however, you should ideally restrict this to a few id attributes. You may also use inline-HTML, but do so only for things you can't get with markdown and don't use it too often.

layout requirements

  • Include only one h1 header (# header in Markdown) in each post, directly after the YAML. It may differ a bit from the title setting in YAML front matter, but should mean the same.
  • Use h2 headers (## header in Markdown) for major sections
  • any headers inside that are h3 followed by h4
    • if possible, avoid use of h5-h7 headers
  • do not use any form elements in the page (if possible)

including code

Syntax-highlighted code can be included in your posts as follows:

{% highlight ahk linenos %}
MsgBox, this is highlighted code
{% endhighlight %}

Use this format in every markdown, also in HTML! Do not wrap it in <pre> or <code> elements!

This enables syntax-highlighting via pygments.

including images

To add images to your posts, place them in the images subfolder of your language subfolder. Then use the respective syntax to add them in your posts. Use relative paths. Example:

![screenshot](images/my-image.png)

Merging your work

When you're done with a set of posts or other modifications, send me a pull request. Usually I'll merge your work after a short discussion.

Clone this wiki locally