Repository navigation
Chapters
Individual chapters are organized in the repository's _chapters/chapters folder.
The book is organized into bigger chapter groups.
This structure can be seen in the table of contents and is reflected in the file structure of the chapters folder.
The content of each chapter is saved in its own Markdown file (.md).
The chapter file starts with a block at the top which is framed by three dashes (---) at the beginning and end.
This is the front matter that contains information for the parser that converts the markdown file to an HTML file.
---
layout: reading_chapter
title: Title
hide: true
permalink: /chapter/category/subcategory/shortTitle/
categories: chapter
---
- The layout field determines the style which is applied to the chapter. It e.g. adapts the icon at the top of the chapter. The following layouts are available:
| Layout | Description |
|---|---|
| reading_chapter | This is a classic text chapter about a topic. |
| tutorial | This chapter mainly consists of hands-on exercises but they do not require programming knowledge. |
| programming_exercise | This chapter mainly consists of a programming exercise. Basic programming knowledge is required. |
- The title field contains the title of the chapter. It will automatically be inserted as a top-level heading on the page. Additionally, this value will also determine the name of the page in the browser's tab.
- The hide field must be set to true. This does not mean that the chapter will not be shown to readers - the chapter page can always be accessed. Instead, it omits an entry in the sidebar. We use this setting since the sidebar is only for the overall navigation in the book whereas chapters can be accessed using the table of contents.
- The permalink value states how the chapter's URL will be constructed relative to its base path.
If the base path is http://www.example.com/ar-for-eu-book/, the example permalink
/chapter/category/subcategory/shortTitle/forms the URL http://www.example.com/ar-for-eu-book/chapter/category/subcategory/shortTitle/. Please, organize the URLs under the chapter path, i.e. start all permalinks for chapters with /chapter/. Moreover, please, if they exist, please use the same category and subcategory names in the path as other chapters in the same subcategory. - The category's value can be used to define tags for each page, e.g. for alternative content indices. All pages which represent chapters should be labelled with the chapter tag.
Below the information block, content can be added in the same way as for a standard Markdown file. See the Markdown page for more resources about formatting markdown files.
Since the file is managed by Git, you should place line breaks in the file behind each sentence. This will not create a line break on the generated Web page but it will help in identifying subsequent changes to individual sentences. Hence, merging different versions of the chapter will become manageable. To create a line break on the Web page, add an empty line (two subsequent line breaks) in the Markdown file.
New chapters can be added by creating a new Markdown file in the _chapters/chapters folder.
Please, add the file in the corresponding category and subcategory folders.
The Markdown file should have the specified structure with the information block at the top.
Additionally, the chapter needs to be inserted into the table of contents.
This file is located in the project's root folder.
Ideally, the table of contents should also be updated in the README file of the respository.
The chapters of the book are pre-planned. It is possible to add new chapters to the book but this should be coordinated with the organizers.