Abstract: This chapter will serve as a comprehensive template for future chapters and contains several sections on important Markdown features that you can use, i.e., tables, images, bullet points and references to the bibliography and table of content.

Example Headline

This is how headlines are created. Use “#” to define them.

The Table of Contents

In order for this page to be linked in the table of contents, please create a header as follows.

---
layout: reading_chapter
title: [The Title of the Chapter]
authors: [Author names]
hide: true
permalink: /chapter/[topic name]/[chapter title]/
---

^{Note, that the above code-block has been created by indenting the lines by 2 tabs.}

Layout

You can select one of several defined layouts for your chapter, that predominantly determine the icon at the start of your chapter. In the following you will find a breakdown on the layouts we would suggest for you and that can be found here in the repository.

Layout type	Description	Icon
reading-chapter	This template is used for standard chapters, created for pure reading purposes.
tutorial	This template can be used for step-by-step tutorials such as for this chapter.
programming-exercise	This template is used for exercises and tutorials where the reader has to code.

^{Please refer to this deployed chapter to see an example for a reading chapter and the corresponding icon on the website.}

Most layouts allow to provide the corresponding authors. These will be listed just below the main title of the page. Apart from this, a layout for posts is provided as well. This layout does not add an icon, yet requires some more attributes in the header that add a date and also an author to the post and should be used for blog posts only. These are found here in the repository. For the layout post, please add the following header.

---
layout: post
title: [My Post Title]
author: [My Name]
date: [The Date]
hide: true
permalink: /post/[post title]/
---

^{Please refer to this deployed post to see a blog post on the website.}

Hide

The parameter hide should always be set to true. This means that it is hidden from the sidebar of the website once built. If set to false, all chapters with this setting will appear in the sidebar and overflow it with links. Thus, this should be avoided. However, the chapter will still be accessible of course by selecting it in the table of contents even if hide is set to true.

Permalink

Each chapter should be given a permalink which serves as an identifier for your chapter. Permalinks define the path on which the chapter will be found on the website and can be different from its path in the repository. This facilitates structuring your content. This permalink is crucial for linking your chapter in the table of content and should be of the form /chapter/[topic name]/[chapter title]/ where [topic name] should be used to refer to the topic area of your chapter and [chapter title] is used to identify the chapter based in its title.

For this template the permalink has been defined to be permalink: /chapter/templates/main-template/ as it belongs to the subfolder and topic area “Templates” and should be identified as the main template. Observe, that this file is indeed in the subfolder “templates”. Although this is not necessary, it proves helpful to structure the chapters in the repository in corresponding subfolders based on the topics that are to be addressed by the DE-TEL book such that navigating the repository is simplified.

Auto Relative Path

Observe that we have added the following line below the file header % include autoRelativePath.html % (inside curly brackets). This include allows you to use a short-hand notation for links the lead to internal resources when including it using HMTL syntax instead of Markdown syntax. See the following example for including the same image these two ways. Note, that concrete examples are given at the end in the Chapter Design section.

• HTML-Notation: <img src="pathToRoot/assets/images/Cover.png"> *
• Markdown-Notation: ![](/detel-book/assets/images/Cover.png)

While the Markdown notation is sufficient to include images, the HTML notation can be more powerful as it allows for captions, image borders etc.

^{Note, that pathToRoot must be enclosed by two pairs of curly brackets to render correctly, which we have removed from the example as it then would automatically be rendered.}

Linking in the Table of Contents

For adding a chapter to the table of contents, navigate to the table of contents file in the repository and add a subtopic to the corresponding main topic area based on your permalink as follows. Your chapter will then appear in the table of contents and be a clickable link to your chapter once the website is deployed.

## Main Topic 

1. [The Title of the Chapter](/detel-book[your permalink])

^{Note, that this template has been added to the table of contents as well and can be used as an example for future chapters.}

Sub-chapters

If you have structured your chapter into multiple sub-chapters - as this chapter is - you are able to specifically refer to these sub-chapters as well and add them to the table of contents. This is not necessary by any means but can allow readers to access certain parts of your chapter quicker if they so desire. This is done by adding a tag to the desired title or subtitle of the section in the shape of (#tag) (see for example the headline of this section ## The Table of Contents {#tableOfContents}). By referencing this tag, the reader is automatically navigated to it. See the following example provided in the table of contents file in the repository where we reference sub-chapters by adding the tag to the permalink.

    ## Templates

    X. [The Main Template](/detel-book/chapter/templates/main-template/)
    1. [The Table of Contents](/detel-book/chapter/templates/main-template/#tableOfContents)
    2. [The Bibliography](/detel-book/chapter/templates/main-template/#bibliography)
    3. [The Chapter Design](/detel-book/chapter/templates/main-template/#chapterDesign)

You can also link these sub-chapters within your chapters creating cross-references. For example, you are currently reading the content of the Table of Contents section. These references are generated upon deployment and do not work while browsing the repository.

The Bibliography

An important feature that you can use in your chapter is citing references that you have documented in a corresponding bibliography file. Doing this, the references will be generated automatically in a similar way to citing using latex, such that you do not have to be concerned about adding and formatting the references in your own chapter. In the following, we will provide an example.

“Chaos isn’t a pit. Chaos is a ladder.” (Sakharov, 2013)

^{Note, that the above quote has been created using a “>” in front of the quoted line.}

Observe, that we cite a reference “GoT”, which is defined in the bibliography file here in the repository as follows. While this is one example for a type of reference you can make, articles, books etc. can easily be referenced as well using different entry types as illustrated by this BibTeX guide. All references defined in this file will be listed under a separate bibliography section on the website as opposed to under your chapter. Note, that % cite GoT % (inside curly brackets) will compile into (Sakharov, 2013) once the chapter is deployed. In this case “GoT” is the identifier of the reference which we cite.

    @movie{GoT,
    title =   {Game of Thrones},
    producer= {Benioff, D. and Weiss, D. B.},
    director = {Alik Sakharov},
    year = {2013},
    }

^{Please refer to the deployed website section to see how the references will be listed.}

Chapter Design

After setting up the core references between your chapter and the table of contents and the bibliography, you are able to enhance the appearance of your chapter with some suggested features.

These include font styles such as strikethrough text, bold text, cursive text, bold and cursive text and headings of different sizes.

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

You can also add listings that can be numbered and nested in each other. Furthermore, task lists can be created and ticked.

1. This is my first numbered item.
   • This is my first unnumbered item.
   • This is my second unnumbered item.
   • This is my third unnumbered item.
2. This is my second numbered item.
3. This is my third numbered item.

• ToDo 1
• ToDo 2
• ToDo 3

Code blocks can be created as follows. It is even possible to specify the language which results in the code being colored accordingly.

Console.WriteLine("Hello World!");

{
"type": "chapter",
"title": "The Main Template"
}

Tables can be generated on this site and improved by defining the text alignment of the individual columns.

You can link external resources as well as other chapters as follows. Note, that you link to another chapter using its permalink in the form of /detel-book[permalink].

Generic Link

Link to another chapter

These images are very large. Another option of including images using HTML lets you set the size in pixels among other things. Aligning text and images either center or right is also possible using the tag <p align="center"> your text </p>. This is illustrated in the following.

I want this image to be aligned to the left.

And this text should align to the right.

I want this image to be centered.

To add figure captions, encapsulate images in <figure> and add the caption as seen in the following example.

<figure>
    <img src="../../../assets/images/Cover.png" alt="Internal Image" width="200px">
    <figcaption>The Cover.</figcaption>
</figure>

^{Note, that the same approaches can be used for linking videos.}

Finally, footnotes are possible to^{1 2}.