# bookdown-guitar: integrating guitar chords into markdown - markdown 里插入吉他和弦指法图

This post was written bilingually, in English and Chinese.

## Introduction

Markdown has been widely used in recent years. With this lightweight markup language, users can easily format plain texts. If using the extended features of markdown, users can even insert footnotes, equations [1], citations, etc. Some software based on markdown, such as Typora [2], even supports flowcharts[3], gannt charts[4], and sequence diagrams [5]. Therefore, markdown is supported on many websites, such as steemit.com, utopian.io, github.com, jianshu.com, stackoverflow.com, etc.

I am kinda a guitar player. I often have to write down guitar chords with lyrics. Commercial software packages cost a lot. I found free software such as LaTeX with some packages, but LaTeX is hard to use, especially for non-programmers. As markdown is free and easy to use, is it possible to integrate guitar chords, just like equations, into markdown files?

The answer was no, until I developed bookdown-guitar.

## Features

bookdown-guitar is an open-source project based on the R package bookdown. Technically, it is a template. You can download it or fork it, and write your own guitar chords out of it. You can change the chord commands as you like, and create some personal chords of your own.

In the meanwhile, bookdown-guitar is more than a template. It is a book as well. I have collected some often-used chords together. I have also collected the lyrics of some pop songs in it, and converted into a pdf book, which is friendly to print. You can use it as a song book or a guitar chord reference book.

Last but not the least, bookdown-guitar is free of charge and cross platform. As it is built in the framework of R environment, bookdown package, markdown syntax, you don’t have to spend a single penny on it. You can use it on Windows, Linux and macOS.

The following images show the guitar book you will get. A song with guitar chords looks like this:

bookdown-guitar support Chinese characters. A Chinese song with guitar chords looks like this:

The collection of the often-used guitar chords is on the last page of the guitar book., which is shown below:

## Quick Start

### Preparation

• Download LaTeX and install it. Choose the right distribution out of MikTeX, TeXLive and MacTeX for your operation system.
• In R environment, run the following codes to install bookdown package.
install.packages('bookdown')


• Unzip bookdown-guitar-master.zip and you will get a folder. You can clone it as well if you have a github account.
• Click the file ‘bdguitar.Rproj’, and it will be opened by RStudio by default.

### Structure of the folder

The structure of the folder ‘bookdown-guitar-master’ is shown as follows.

bookdown-guitar-master
│  bdguitar.Rproj
│  cd.Rmd
│  hallelujah.Rmd
│  hh.Rmd
│  index.Rmd
│  index.txt
│  mk.Rmd
│  sqxy.Rmd
│  ybgs.Rmd
│  ybzsqln.Rmd
│  zzz_toolbox.Rmd
│  _bookdown.yml
│  _output.yml
├─css
├─images
├─latex
│      after_body.tex
│      before_body.tex
│      chordbox.tcl
│      preamble.tex
│      preamble_backup.tex
│      template.tex
│      _gchords.sty
├─_book
│  │  bdguitar.epub
│  │  bdguitar.pdf
│  │  bdguitar.tex
│  │  cd.html
│  │  hallelujah.html
│  │  hh.html
│  │  index.html
│  │  method.html
│  │  mk.html
│  │  search_index.json
│  │  sqxy.html
│  │  toolbox.html
│  │  ybgs.html
│  │  ybzsqln.html
│  ├─bdguitar_files
│  ├─css
│  ├─images
└─_bookdown_files


The beginners don’t have to understand most of these files, except .Rmd files, which contains lyrics and guitar chords in them. The demo book is in the _book folder. You can view the bdguitar.pdf with any pdf viewer.

### Examples

Open hallelujah.Rmd file, as an example, in RStudio. You will see a text editor window as follows.

The commands beginning with \ are the guitar chords. \CM means C major, \Am means A minor, and so on so forth. There are guitar chords already inserted into the first paragraph as a demo. You can insert some chords into the second paragraph like this:

Your \CM faith ~~was~~ **strong**
But you \Am needed [proof](https://utopian.io)

You \CM saw her bathing
\Am On the roof

Her \F beauty and the Moonlight
\CM overthrew you \GM


You can change the format of the text with markdown syntax as shown above.

Then click the Build Book button on the top right, then bookdown::pdf_book (instead, you can do it via the hot key ctrl+shift+b). The guitar book will be updated.

After several seconds (it depends on your computer’s calculation power), a pdf file will be opened automatically, and you will see the guitar book updated as follows.

As it is a book for printing, the format of hyperlink is converted into footnote.

Advanced users might want to know how it works and how to insert other guitar chords not shown in the example. This is going to be written in a tutorial if anyone is interested in it. Shortly speaking, please read the manual of the LaTeX package ‘gchords’ [6] and then find the definition of the chord commands in ‘/latex/preamble.tex’.

https://github.com/pzhaonet/bookdown-guitar

## Proof of Work

In my profile on Utopian.io, the github repo pinyin is listed in my project page, which is show in the screenshot as follows:

The commit page on github.com is shown in the following screenshot:

## References

bookdown-guitar 是个基于 R 语言扩展包 bookdown的 开源项目。本质上，它是个模板。你可以下载或者 fork 这个模板，在其基础上写你自己的吉他谱。你也可以随心所欲更改吉他谱的插入命令。当然，你也可以创建新的和弦指法图。

## 快速入门

### 准备

install.packages('bookdown')


### 下载或克隆 bookdown-guitar

• 访问 bookdown-guitar 的主页: https://github.com/pzhaonet/bookdown-guitar
• 解压缩，会得到一个文件夹。当然，如果你有 github 账号，也可以克隆这个项目。
• 双击 ‘bdguitar.Rproj’ 文件，在 RStudio 里打开。

### 示例

\ 开头的命令就是吉他和弦谱。 \CM 表示 C 大三和弦， \Am 表示 A 小三和弦。

Your \CM faith ~~was~~ **strong**
But you \Am needed [proof](https://utopian.io)

You \CM saw her bathing \Am On the roof

Her \F beauty and the Moonlight
\CM overthrew you \GM