last updated by Jack Dougherty on March 16, 2017
- Folder/file structure for this GitBook:
- Table of Contents
- Compose in Markdown for GitHub/GitBook
- GitBook Plugins
- Insert HTML comments in GitBook Markdown
- Use Code-Fencing in Markdown
- 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)
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
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:
- A chapter in the GitHub repository: https://github.com/JackDougherty/datavizforall/blob/master/map/point-gft/README.md
- The same chapter on GitBook (which converts README.md to index.html): http://www.datavizforall.org/map/point-gft/index.html
- Abbreviated web address to same chapter (since "index.html" is not required):
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.
Upload images into the chapter folder, and insert the reference in this format:
TO DO: Insert image descriptions between the square brackets to make book accessible to visually impaired readers.
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
Since the youtubex plugin is installed in this Gitbook, embed videos in the text this way:
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 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)
To display non-executed code within Markdown for GitHub/GitBook, follow this code-fencing format:
- insert the non-executed code to display
- insert three closing backticks.
```html <iframe src="https://assets-cdn.github.com/images/modules/contact/heartocat.png"> ``` (end of example)
Improve this book: Donate to DataViz students and add comments or revisions.