Quirks for writing pages and blog posts

1. Links

The project directory structure gives an idea of how the web site is structured too. In the project root directory, you will find an index.md file. That file is rendered by Jekyll as index.html. Besides rendering the Mardown content as HTML, Jekyll also replaces variables by the right values.

In order to use links, you can use the variable site.baseurl. Like the following example.

Follow the instructions <a href="{{ site.baseurl }}installing-plugins.html" title="Installing plug-ins">here</a> to install the plug-in.

Here, site.baseurl resolved to the root URL, which, by its turn, is also related to the project root directory. There you should find a file that matches the user request. In this case, installing-plugins.md.

2. Markdown and HTML

Even though you write pages and posts in Markdown, the content is rendered by Jekyll as HTML. It not only converts Markdown into HTML, but also replaces variables by its right values.

3. Markdown syntax

Some times your content may be valid Markdown but not correctly rendered after you commit it. The reason for that is that GitHub pages require that your Markdown syntax follow certain rules, specially regarding break lines.

If your code contains headers, for instance, they should be separated from other lines by at least one blank line. In other words.

# Title
Text

Won't be displayed correctly. But;

# Title

Text

Will be. The same for code blocks. In most cases, keeping paragraphs and elements separated from each other by a blank line is quite safe, and should help your pages to be correctly rendered.

4. Tables

Tables are rendered by the browser, with certain CSS styles. The current theme of our site uses Pure CSS. Some other sites use Bootstrap, Semantic UI, Foundation, Grid, etc. Tables - and other

HTML elements - may be rendered differently depending on the framework. But normally elements are marked to be rendered in some way by using classes or ID's.

Pure CSS uses the pure-table CSS class. So if you add a Markdown table (or even an HTML table), you also need to set the CSS class. The current Markdown library in GitHub pages/Jekyll supports the following syntax:

{:.class-name}
| table ...|

By adding the class name to your table, as above, you should see it rendered correctly.