In ratnanil/songbookdown: An easy and flexible way to create songbooks

How do I get started?

Assuming you have a fairly new version of R and an IDE installed (e.g. RStudio), install bookdown and songbookdown. If you want to produce pdf later on, install tinytex and run the function install_tinytex().

install.packages("bookdown")
devtools::install_github("ratnanil/songbookdown")

# to produce pdf outputs later on:
install.packages("tinytex")
tinytex::install_tinytex()

And then?

Next, create the files minimally needed for bookdown project. This consists of the following files:

[x] _bookdown.yaml
[x] index.Rmd
[x] a folder where the (intermediate) Rmd files can be stored (e.g. rmd)
[x] a folder where the book is compiled to (e.g. docs)

Additionally, songbookdown requires the following files:

[x] _songbookdown.yaml
[x] a folder where the raw song-files are stored. (e.g. songs_raw)

These files can be generated using the function create_template()

How do I add a new song?

Add subfolders to songs_raw. These subfolders will create different chapters in your book, e.g. "Classics" and "Christmas Songs".

Create a plain text file (e.g. mysong.txt) in one of the subfolders of songs_raw and import the song into this file. You can add metadata in the yaml format, wrapped with tripple dashes (see below).

---
title: Here Comes the Sun
artist: the Beatles
year: 1969
---

Here comes the sun
Doo doo doo doo
Here comes the sun and I say
It's alright
...

What metedata can I add and how is this used?

You can add any metadata in this form, and this data will be displayed in a tabular fashion at the end of the song. Some keywords have a special meaning:

title is required and used to build the songs's header.
title, artist, composer, lyricist and album are used in the glossary.
declaring the source is recommened.

Even if you can add any metadata, using the chordpro syntax is recommended. Here's a list of keywords that are used in the chord-pro syntax:

title
subtitle
artist
composer
lyricist
copyright
album
year
key
time
tempo
duration
capo
source

What about the rest of the song?

Add the rest of the song in plain text. It will be rendered into a monospaced font where lines are not broken. The reasoning behind this is that you can copy and paste plain text songs from sources like ultimate-guitar.com where monospacing helps keep chords and text aligned.

You add further structure to the song in a chordpro type manner. From the chord pro syntax, the following environment directives are implemented (short forms only).

{start_of_chorus}
{end_of_chorus}
{chorus}
{start_of_verse}
{end_of_verse}
{start_of_bridge}
{end_of_bridge}
{start_of_tab}
{end_of_tab}
{start_of_grid}
{end_of_grid}

As in the chordpro specification, all environment directives may include an optional label to identify the section. For example: {start_of_verse: Verse 1} The label should not include special characters and must be seperated from the : with a space.

How do I add a new chapter into the book?

Create a subfolder in the songs_raw folder. Add the name of the folder to subfolders: in _songbookdown.yml and add a title.

subfolders: 
  mynewfolder:
    title: The title of the new chapter (required) 
    description: |
      An optional description
      that can span over muliple lines
      (currently this description is not used anywhere,
      but will be implemented in the near future)