Bookdown contest submission: backyard, A Web App for Easier Bookdown Collaboration

[colin]

So, it's still a POC, but as we are coming closer and closer to the deadline, I'm submitting this for the contest today, and I hope I'll have some time before the 1st to work on a few issues

GitHub - ColinFay/backyard: A Web App for Easier Bookdown Collaboration

See below for current known limitations and plan for future development.

About {backyard}

{backyard} is a shiny app that provides a visual backend for easier collaboration on Bookdown
projects.

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

{backyard} is

• Open source: code is on GitHub, under MIT licence.
• Format agnostic: launched with markdown_only set to TRUE (default), the user can only create/edit markdown compatible tags. The preview will always be a Gitbook, but the edited Rmd can be knitted to any format.
• Documented: A full documentation is available at About {backyard}, including how to install, use and deploy (a documentation written with {backyard})

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 a bookdown project. 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 : In that case, you’ll need to point to the folder where you want your bookdown to be saved, and add a folder name. The default Bookdown template is used.
• point to an Index.Rmd of a bookdown already there on the machine

You can pass to backyard::run_app() the location of the index.Rmd
(then the app is launched for this bookdown only).

You can also provide a home location, which will be the 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.

Preview

At any time, you can open a modal that runs a preview of the book (doesn't render well on firefox for now, but I'm working on it)

About

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

Chapters

This tab has 2 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, reorder chapters

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:

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 "contact@colinfay.me"

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 /home/bookdown

EXPOSE 2811

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

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 "contact@colinfay.me"

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

RUN mkdir /home/bookdown

COPY bookdown /home/bookdown/mybook

EXPOSE 2811

CMD R -e "backyard::run_book(indexrmd = '/home/bookdown/mybook/index.Rmd',host = '0.0.0.0')"

Notes on Docker

• By default, {backyard} is deployed on port 2811. It can be changed
  in backyard::run_app.
• 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:

• Not all bookdown has been tested, so some might crash (feel free to open an issue if you find one)
• 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.
• It's not possible to download the book (for now)

TODO

List of things left to do so far are on Issues · ColinFay/backyard · GitHub

Future work

I'm planning on extending {backyard} so that it can:

• Make all the Rmd in a folder editable (with run_dir)
• Make one Rmd editable (with run_rmd)

As this is for now focused on the bookdown contest, these options have not been set.

[dapeng]

Wow, looks amazing! I am much interested in your bookdown UI. However, I cannot either create a new bookdown project or open an existing one with backyard. Only the folders in my root directory are displayed. Is it because I have a Windows 7 OS?

[colin]

Hey @dapeng

Thanks for pointing that out.

I've changed the default of the home argument to ., so that it starts in your working directory, and it is cross-platform (should work everywhere).

If you want to change, feel free to use :

backyard::run_app(home = "C://") seems to work:

Thanks for pointing that, I'll add it to the documentation.

Let me know if it does the trick, you can either reinstall the package from GitHub or simply do backyard::run_app(home = "C://") or backyard::run_app(home = ".")

[rensa]

I haven't had a chance to play with this, but it looks SO DANG COOL

[dapeng]

awesome! Now it is working on my Windows 7. I enjoyed a while, and got a feeling that backyard, compared to bookdown itself, is something like ggplot2 to the basic plotting functions. On one hand, it is surely much easier, more friendly and elegant to bookdown beginners. On the other hand, it is a whole new world on the basis of bookdown. I guess this is exactly what the first bookdown contest is expecting.

Thank you very much for your update.

[mczyz]

Amazing stuff and extremely needed. I work with people with no skills in R, LaTeX, html, etc. and this would benefit our work soooo much. As soon as i finish my stuff I will play with it:)

[colin]

Thanks, that's exactly what this aims at: facilitate collaboration between R-nerds ans non-tech folks

[yihui]

Well, I'm going to ask the same question you asked earlier this year: WHAT KIND OF SORCERY IS THIS?

This is such a creative and useful package! I learned document.execCommand() for the first time. There seems to be still a lot of new things I could learn, but I guess I'd better hold my curiosity and finish reviewing all the contest submissions first!

Thanks for the wonderful package!

[colin]

Thanks a lot Yihui!

I learned a lot doing this one

There are still a lot of things I want to explore with this one, I really hope this will make collaboration easier on bookdown-based project.

This idea has been on the back of my head for a while, it was cool to have a good reason to start. Thanks for making this contest happen!

[jtbayly]

This looks amazing. Is it still being developed?

Is there any place I can try it out?

[colin]

@jtbayly yeah I've been procrastinating a lot on this one, so it has not been improved for a while but it should be... soon

I need to find some time to work on this again.

There is no online demo for now, but if you install the package from GitHub and try it locally, it should definitely work

Let me know if you have any question!

Colin

[jtbayly]

Thanks, but I don't understand where the single command to install the package is supposed to be run: remotes::install_github("ColinFay/backyard")

I'm on a mac. I tried it in Rstudio as well as in Terminal, just for kicks, even though I was pretty sure that didn't look like any sort of command that would work in Bash. Both threw errors.

Perhaps it's only for Linux, or particular styles of Linux?

A bit more detail in the documentation would be helpful, or else I'm just missing it.

Edit: I tried, based on the error, to find a way to install a "remotes" package, and found something in the UI. Looks like the command is intended to be run R Studio, but you have to run this command first: install.packages("remotes")

[colin]

Thanks @jtbayly. I'm sorry about that, I was under the impression that using the this::function notation was a clear sign that it's a package and a function...

Writing documentation is hard, and it's even harder to draw the line on what we think are common knowledge

Yes, you have to install the {remotes} package first. You can either launch it in RStudio or in any terminal with R open, even with R -e install.packages("remotes") in your unix terminal.