Close rstudio#638: Add option for a history button (rstudio#639)

R/gitbook.R

@@ -138,9 +138,12 @@ gitbook_page = function(
   }
 
   # you can set the edit setting in either _bookdown.yml or _output.yml
-  if (is.list(setting <- edit_setting(config$edit))) config$edit = setting
-  if (length(rmd_cur) && is.list(config$edit))
-    config$edit$link = sprintf(config$edit$link, rmd_cur)
+  for (type in c('edit', 'history')) {
+    if (is.list(setting <- source_link_setting(config[[type]], type = type)))
+      config[[type]] = setting
+    if (length(rmd_cur) && is.list(config[[type]]))
+      config[[type]][["link"]] = sprintf(config[[type]]$link, rmd_cur)
+  }
 
   config$download = download_filenames(config)
 
@@ -215,6 +218,7 @@ gitbook_config = function(config = list()) {
     ),
     fontsettings = list(theme = 'white', family = 'sans', size = 2),
     edit = list(link = NULL, text = NULL),
+    history = list(link = NULL, text = NULL),
     download = NULL,
     # toolbar = list(position = 'static'),
     toc = list(collapse = 'subsection')

R/html.R

@@ -187,7 +187,8 @@ build_chapter = function(
     chapter,
     '<p style="text-align: center;">',
     button_link(link_prev, 'Previous'),
-    edit_link(rmd_cur),
+    source_link(rmd_cur, type = 'edit'),
+    source_link(rmd_cur, type = 'history'),
     button_link(link_next, 'Next'),
     '</p>',
     '</div>',
@@ -430,21 +431,21 @@ button_link = function(target, text) {
   )
 }
 
-edit_link = function(target) {
+source_link = function(target, type) {
   if (length(target) == 0) return()
-  setting = edit_setting()
+  setting = source_link_setting(type = type)
   if (is.null(setting)) return()
   button_link(sprintf(setting$link, target), setting$text)
 }
 
-edit_setting = function(config) {
-  config_default = load_config()[['edit']]
+source_link_setting = function(config, type) {
+  config_default = load_config()[[type]]
   if (missing(config) || is.null(config)) config = config_default
   if (is.null(config)) return()
   if (is.character(config)) config = list(link = config, text = NULL)
   if (!is.character(link <- config[['link']])) return()
-  if (!grepl('%s', link)) stop('The edit link must contain %s')
-  if (!is.character(text <- config[['text']])) text = ui_language('edit')
+  if (!grepl('%s', link)) stop('The ', type, ' link must contain %s')
+  if (!is.character(text <- config[['text']])) text = ui_language(type)
   list(link = link, text = text)
 }
 

inst/examples/03-formats.Rmd

@@ -144,7 +144,8 @@ The second button on the toolbar is the search button. Its keyboard shortcut is
 
 The third button is for font/theme settings. You can change the font size (bigger or smaller), the font family (serif or sans serif), and the theme (`White`, `Sepia`, or `Night`). These settings can be changed via the `fontsettings` option.
 
-The `edit` option is the same as the option mentioned in Section \@ref(configuration). If it is not empty, an edit button will be added to the toolbar. This was designed for potential contributors to the book to contribute by editing the book on GitHub after clicking the button and sending pull requests.
+The `edit` option is the same as the option mentioned in Section \@ref(configuration). If it is not empty, an edit button will be added to the toolbar. This was designed for potential contributors to the book to contribute by editing the book on GitHub after clicking the button and sending pull requests.  The `history` option works the same
+way.
 
 If your book has other output formats for readers to download, you may provide the `download` option so that a download button can be added to the toolbar. This option takes either a character vector, or a list of character vectors with the length of each vector being 2. When it is a character vector, it should be either a vector of filenames, or filename extensions, e.g., both of the following settings are okay:
 

inst/examples/04-customization.Rmd

@@ -202,6 +202,7 @@ We have mentioned `rmd_files` in Section \@ref(usage), and there are more (optio
 - `before_chapter_script`: one or multiple R scripts to be executed before each chapter, e.g., you may want to clear the workspace before compiling each chapter, in which case you can use `rm(list = ls(all = TRUE))` in the R script.
 - `after_chapter_script`: similar to `before_chapter_script`, and the R script is executed after each chapter.
 - `edit`: a link that collaborators can click to edit the Rmd source document of the current page; this was designed primarily for GitHub repositories, since it is easy to edit arbitrary plain-text files on GitHub even in other people's repositories (if you do not have write access to the repository, GitHub will automatically fork it and let you submit a pull request after you finish editing the file). This link should have `%s` in it, which will be substituted by the actual Rmd filename for each page.
+-  `history`: similar to `edit`, a link to the edit/commit history of the current page.
 - `rmd_subdir`: whether to search for book source Rmd files in subdirectories (by default, only the root directory is searched). This may be either a boolean (e.g. `true` will search for book source Rmd files in the project directory and all subdirectories) or list of paths if you want to search for book source Rmd files in a subset of subdirectories.
 - `output_dir`: the output directory of the book (`_book` by default); this setting is read and used by `render_book()`.
 - `clean`: a vector of files and directories to be cleaned by the `clean_book()` function.

inst/resources/gitbook/js/plugin-bookdown.js

@@ -16,6 +16,18 @@ gitbook.require(["gitbook", "lodash", "jQuery"], function(gitbook, _, $) {
       }
     });
 
+    // add the History button (file history on Github)
+    var history = config.history;
+    if (history && history.link) gitbook.toolbar.createButton({
+      icon: 'fa fa-history',
+      label: history.text || 'History',
+      position: 'left',
+      onClick: function(e) {
+        e.preventDefault();
+        window.open(history.link);
+      }
+    });
+
     var down = config.download;
     var normalizeDownload = function() {
       if (!down || !(down instanceof Array) || down.length === 0) return;