README.md

In ColinFay/backyard: A Web App for Easier Bookdown Collaboration

Words of caution: this is still a WIP. Use carefully, and don’t forget to backup your bookdwon before using the app.

backyard

The goal of backyard is to provide a visual backend for collaboration on Bookdown projects.

Why {backyard}?

The main idea is that, with a {backyard} backend, users can focus on writing and don’t have to know anything about Markdown and/or about R & {bookdown} to get involved in the writing of a bookdown. This would facilitate collaboration between those who use R and those who don’t.

Once deployed, a {backyard} backend is easy to access and use, and is suitable for tech/non-tech people.

When would you need {backyard}

There are many situations where you might need {backyard}. Here are few ideas:

• You want your partner/parents/friends to proof-read your bookdown, but they don’t know anything about R and/or markdown. Let them re-read your content with a {backyard} backend.
• You are collaborating on a book with someone who is not an R aficionados.
• You’re a group of students doing group work at your university, and need a way to easily collaborate on the content.
• You’re more comfortable with using a visual backend.
• You want to provide a central server for writing books or manual in your company …

How is a {backyard} backend organized?

Launch

backyard::run_book() (without any parameter filled) opens an invite box that can either be used for creating a new bookdown (point to the folder where you want your bookdown to be saved, and add a folder name), then the default Bookdown template is used, or to point to an Index.Rmd of a bookdown already present on the machine.

You can pass to backyard::run_book() the location of the index.Rmd (then the app is launched for this bookdown), or the location of your home (for the folder selection invite, default is .).

By default, the safe_mode parameter is set to TRUE. This mode creates, at launch time, a copy (in {path}/backyard_copy) of your current version of the bookdown folder. That way, if ever you do something wrong during your backyard session, you can still go back to the previous version.

The markdown_only parameter, set to TRUE by default, informs if you want to keep only the markdown-compatible tags, and then will only display markdwown compatible buttons in the wysiwyg interface. If turned to FALSE, you’ll get more button, but when saved, the .Rmd will contain html tags.

About

This first page gives you a quick overview of the book. Nothing fancy here.

Chapters

This tabs has 3 other tabs

• Chapter edit: edit a chapter in html with the WYSIWYG (What you see is what you get) editor. Don’t forget to save when you’re done. If you’re more comfortable with markdown, you can also use the “update as Markdown” interface of this window.
• Manage Chapter: Add, delete, rename chapters
• Reorder Chapter: reorder the chapter of the books with drag and drop

About code blocks in interactive mode

Code blocks are, on purpose, not editable in Interactive mode. You should switch to Markdown mode if you want to edit these elements.

Options

The idea of this tab is that non-tech people don’t want to enter too many technical details, hence they have “textual” content to see. If you want to dig into the tech, two tabs can be used to do that?

• Global: edit some global options with a nice UI
• Edit options: change the options of Index.Rmd, _output.yml and _bookdown.yml just as if you were in any editor
• Edit any file: open an editor for any file contained in same directory as the index.Rmd.

Design

• CSS: edit, create and delete CSS files
• Highlight: change the book syntax highlighting

Installation

You can install the dev version of backyard with:

# install.packages("remotes")
remotes::install_github("ColinFay/backyard")

Deploy

The best way to collaborate with this is to deploy this app on a server.

Here a minimalist Docker file that can launch a {backyard} backend:

FROM rocker/tidyverse

MAINTAINER Colin FAY "[e-mail]"

RUN R -e "install.packages('remotes', repos = 'https://cran.rstudio.com/')"
RUN R -e "remotes::install_github('ColinFay/backyard')"

# Create a folder just for bookdowns
RUN mkdir /usr/home/bookdown

EXPOSE 2811

CMD R -e "backyard::run_book(host = '0.0.0.0', home = '/usr/home/bookdown')"

You can find this dockerfile in the inst/ folder of the package.

If you only wants to share one bookdown (assuming the boookdown is in the same dir as the Dockerfile):

FROM rocker/tidyverse

MAINTAINER Colin FAY "[e-mail]"

RUN R -e "install.packages('remotes', repos = 'https://cran.rstudio.com/')"
RUN R -e "remotes::install_github('ColinFay/backyard')"

RUN mkdir /usr/local/bookdown

COPY bookdown /usr/bookdown/bookdown

EXPOSE 2811

CMD R -e "backyard::run_book(indexrmd = '/usr/bookdown/bookdown',host = '0.0.0.0')"

Notes on Docker

• By default, {backyard} is deployed on port 2811. It can be changed in backyard::run_book.
• If you launch the app in a Docker container, be sure to use host = '0.0.0.0'

Known limitations

This project is still experimental, so there might be bugs in the interface. Here are some we know of:

• Only git book format is supported (for now)
• Preview doesn’t work perfectly in Firefox (CSS issue)
• If you want to preview or render a book, it must compile on the machine it is located: all packages in the bookdown should be installed there, for example.
• For now, you can’t change the chunks parameters with the HTML editor (will come some day)

TODO

• Write a documentation bookdown
• Better Design
• Add other formats
• Better download API

Please note that the ‘backyard’ project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

ColinFay/backyard documentation built on June 29, 2019, 3:54 p.m.