Updates regarding the wiki port

[qreeves]

OK, so we've seen some good work being done on porting the wiki to markdown, but there have been a few teething issues that I now need to address. This is a work in progress, so there may be updates; I'll include a comment when I make changes. This shouldn't be turned into a documentation page until we've solidified the content.

The Location

Using the built-in GitHub wiki doesn't work quite as well as a normal repository, so I'm disabling wikis and moving the existing work to the Docs Repository. If you've already check out the existing wiki you should be able to just set the new location and pull from there:

git remote remove origin
git remote add origin https://github.com/red-eclipse/docs.git

By using a normal repository we'll be able to do the proper post-commit actions like IRC channel announcements and automatic deployments to the Beta Website.

The Style

I didn't set a style guide to begin with because I was unsure of what to expect and unaware of any cross-compatibility issues. As I mentioned, the documentation will be automatically deployed to the Beta Website, and this involves going through a few steps using GitHub Pages. Basically there are two "pre-processors", Jekyll, and Kramdown. It is necessary to understand the unique syntax of each when crafting your markdown pages.

Headers

All headers should be presented in ATX format, Setex format is not supported. This means you create headers with the hash symbol (#), and not a line followed by a series of dashes (-). It is important to note that the title of the page will always be the first-level header (a single #), and your documents should always start with second-level headers (two ##).

## First-level header in document
Text that goes after that.

### Second-level header in document
Text that describes what the second level is about.

Tables

Your tables need to have an empty line before the first entry. Jekyll does not support rendering all table types without this being done.

Correct

Blah blah blah...

| Header | Information |
|--------|-------------|
| Item 1 | Item 1 data |
| Item 2 | Item 2 data |
| Item 3 | Item 3 data |

Incorrect

Blah blah blah...
| Header | Information |
|--------|-------------|
| Item 1 | Item 1 data |
| Item 2 | Item 2 data |
| Item 3 | Item 3 data |

Images

It is inevitable that you are going to want to include images in your documents, and in most cases you are going to need to resize them in the page, which isn't something that is inherently supported by markdown. In these cases you can use the <img> HTML tag with some conditions:

• The tag should only be used if you need to do some sort of styling (like resizing, etc)
• You should not link to an outside source. Any images needed should be copied to the images directory in the docs repository.

Paths

All paths need to be relative to each other. The docs repository is converted to GitHub Pages and sits in the docs directory, not at the root.

Table of Contents

Kramdown supports the automatic generation of these, and the pages are automatically generated to include them. You do not need to create your own at the top of your pages.

[IceflowRE]

The collons : in tables are for align the stuff inside the columns, so you dont want it?

[qreeves]

@IceflowRE: It doesn't work in Jekyll, so unless you can find another way to do it, no.

[IceflowRE]

Just to complete it, the table with | and : are possible, just make sure theres an empty line before the table.

[qreeves]

Updated original post with what @IceflowRE has learned.

[IceflowRE]

For those who want to try how it looks offline (not a perfect solution but it worked fast and dirty):

1. Install ruby
2. clone https://github.com/red-eclipse/red-eclipse.github.io
3. delete the doc folder
4. clone https://github.com/red-eclipse/docs into a new doc folder
5. add this file (Gemfile) to the main folder

source 'https://rubygems.org'
gem 'github-pages'

6. execute gem install bundler
7. execute bundle install
8. execute bundle exec jekyll serve
9. open http://localhost:4000/ in your browser

For the documentation markdowns, you have to add to the top:

---
title: <title>
origfile: <origfile>
layout: docs
---
* TOC
{:toc}

<title> and <origfile> can be everything and dont need to be a specific value.

However if i missed something tell me, because i dont remember everything what i tried.