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
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 toTRUE
(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
inbackyard::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.