Contributing to this Documentation

This page includes information on how to extend the documentation provided on this homepage. The homepage itself is created using Jekyll, which needs to be installed if you want to test your changes locally (this is highly encouraged).

You need to have an account on our development repositories to push changes.

The general process of cloning a repository, creating a new feature branch, and submitting the branch and a corresponding merge request is outlined in the GitLab Documentation.

Prerequisites

Clone the website repository to create a local working copy:

git clone git@dev.kom.e-technik.tu-darmstadt.de:simonstrator/simonstrator-website.git

Next, follow the installation procedure of Jekyll, as documented on their homepage. Afterwards, you need to install a few additional gems:

sudo gem install jekyll-paginate jekyll-sitemap jekyll-gist jekyll-feed

Now, try serving the website locally:

jekyll serve --config _config.yml,_config.dev.yml

You should now be able to reach the current version of the site at http://localhost:4000/simonstrator/.

Editing a Page

Assuming you just want to update or extend an already existing page, the steps are quite simple. All documentation is stored within the _docs folder as a set of markdown-files1. Just find and edit the respective file and save your changes. If you are not already serving the website locally, run

jekyll serve --config _config.yml,_config.dev.yml

and navigate to the page you altered to check if everything was updated correctly.

Once you completed your changes, simply submit your state to the upstream repository as a new branch and create a merge request via the GitLab homepage.

Adding a new Page

Providing content for the existing structure of the documentation (left navigation bar) is encouraged over submitting completely new segments.

Start by duplicating one of the existing documentation pages within the _docs-folder, and rename the file according to its planned content. The number preceding the file name specifies the order of pages when using the next and previous links on each page and should correspond to the order of pages in the navigation view on the left side. Alter the front matter of the new document:

---
title: Title of the page
permalink: /docs/link-to-the-page/
excerpt: Brief one-sentence summary
---

Now, just add your content, ensuring that the table of contents and the include-statement for the page root remain right after the front matter:

{% include base_path %}
{% include toc %}

Your content.

Next, you need to ensure that you page is correctly linked to in the navigation bar on the left of the homepage. Therefore, open the _data/navigation.yml file:

docs:
  - title: 1. Getting Started
    children:
      - title: Quick-Start Guide
        url: /docs/quick-start-guide/
      - title: Project Structure
        url: /docs/work-in-progress.html

Assuming you just provided a documentation file for the segment Project Structure with the permalink docs/project-structure/, simply alter the corresponding url: entry:

docs:
  - title: 1. Getting Started
    children:
      - title: Quick-Start Guide
        url: /docs/quick-start-guide/
      - title: Project Structure
        url: /docs/project-structure/

Reload the page (and ensure it has been recompiled) to check if the page is linked correctly.

Once you completed your documentation entry, simply submit your changes to the upstream repository as a new branch and create a merge request via the GitLab homepage.

Formatting Options

As the site supports the full markdown-syntax1, you can easily add code blocks with syntax highlighting and other helpful information to your documentation page. For a full list of commands and options, please refer to the markdown documentation.

Linking to internal pages

When linking to other pages of the documentation or news entries, ensure that you prefix the link with the {{ base_path }} tag. For example, to link to this page in markdown, you would write:

Learn how to [contribute]({{ base_path }}/docs/contributing/documentation/)

Including images

Add images to the images/docs/... folder, ideally creating a subfolder for your new entry. Ensure that they are named in a human-readable fashion, without blanks or other special characters in the file name. Within your markdown file, you can now simply include the image by writing

![Brief description of the image]({{ base_path }}/images/docs/path-to-your-image.png)

Note that you can further style the appearance of the image, please check the template documentation for detailed examples.

  1. To learn more about the markdown syntax, visit http://kramdown.gettalong.org/syntax.html  2

Updated: