Structure, Plugins, and Syntax

last updated by Jack Dougherty on March 16, 2017

Folder/file structure for this GitBook:

  • Part folder (example: map)
  • Chapter subfolder (example: map/point-gft)
  • Chapter text (example: map/point-gft/README.md)
  • Chapter images (example: map/point-gft/visual.png)

Table of Contents

GitBook requires a SUMMARY.md file, which organizes the table of contents. View the SUMMARY.md file for this GitBook at: https://github.com/JackDougherty/datavizforall/blob/master/SUMMARY.md

Compose in Markdown for GitHub/GitBook

Markdown is an easy-to-read syntax that is simpler than HMTL and growing in popularity across many digital platforms. GitBook follows most of GitHub Flavored Markdown syntax: https://help.github.com/articles/getting-started-with-writing-and-formatting-on-github/

See also GitBook Markdown guide: https://help.gitbook.com/format/markdown.html

Inside each chapter folder, the main text is stored in the README.md file, to simplify the GitBook web addresses. Example:

Insert brackets around the words to be underlined, followed by parentheses for the embedded link, like this:

Regular text [with underlined hotlink](http://anywhere.com)

For internal relative links to other chapters of this GitBook, which is organized into parts. Also, add the phrase this book to the text to assist when searching for internal book links to revise, using the Find in Project menu in Atom Editor.

Example 1: pathname points to folder, at the same level, with a default README.md file (which requires no direct reference)

[Go to this chapter](gitbook) in this book

Example 2: pathname points to folder, up one level, with a default README.md file (which requires no direct reference)

[Go to a different part](../choose) in this book

Example 3: pathname points to folder, up two levels, and a specific .md file name (not default README.md)

[Help us improve this book](../../gitbook/improve.md)

Example 4 in theory: For internal links to downloadable sample files, upload them into the GitBook and insert a link. The text inside brackets CANNOT include a file suffix (.csv).

Right-click this link and Save to download to your computer: [sample](sample.csv). CSV means comma-separated-values, a generic spreadsheet format that many tools can easily open.

Example 4 in practice: In GitBook Slack thread 15 March 2017, @nagim states known problem using Gitbook 3.2.2, if you put a link to a file that is not a Markdown/AsciiDoc file (for example, .txt files), and is part of the repository (stored at the same folder structure as the essay), the links do not work, probably due to an issue in the theme, which he will post. In the meantime, use this workaround:

Click this link and Save to download to your computer: [sample-address-data in CSV format](https://www.datavizforall.org/choose/rate/sample-address-data.csv). CSV means comma-separated-values, a generic spreadsheet format that many tools can easily open.

Embed images in GitBook Markdown

Upload images into the chapter folder, and insert the reference in this format:

![](image.png)

TO DO: Insert image descriptions between the square brackets to make book accessible to visually impaired readers.

GitBook Plugins

Plugins extend the features of basic GitBook, and are configured in the book.json file. View the entire repository of GitBook plugins: https://plugins.gitbook.com/

View the plugins and configurations used in this book at: https://github.com/JackDougherty/datavizforall/blob/master/book.json

Embed YouTube Video with GitBook Plugin

Since the youtubex plugin is installed in this Gitbook, embed videos in the text this way:

{%youtube%}ZVejLE8qtOI{%endyoutube%}

The YouTube video will appear as an embedded iframe in the online web version of the GitBook, and as a link in the ebook versions.

Insert HTML comments in GitBook Markdown

  • Insert HTML comments for notes that are not visible to GitBook readers (but are visible on the GitHub public repo)
     <!-- TO DO: Revise this page -->
  • Insert HTML iframe for interactive elements (which are visible on GitBook web edition, but not in ebook editions; perhaps in future)
<iframe src="https://assets-cdn.github.com/images/modules/contact/heartocat.png">

Use Code-Fencing in Markdown

To display non-executed code within Markdown for GitHub/GitBook, follow this code-fencing format:

  • insert three backticks (`) followed by the language (typically html or javascript)
  • insert the non-executed code to display
  • insert three closing backticks.

Example:

```html
<iframe src="https://assets-cdn.github.com/images/modules/contact/heartocat.png">
```                         (end of example)

Data Visualization For All is copyrighted by Jack Dougherty and contributors and distributed under a Creative Commons Attribution-NonCommercial 4.0 International License. You may freely share and modify this content for non-commercial purposes, with a source credit to http://DataVizForAll.org.
Improve this book: Donate to DataViz students and add comments or revisions.

results matching ""

    No results matching ""