In grunwaldlab/quiltr: Automated website creation from scattered HTML

NOTE: This documentation is out of date

I will be updating it soon. The main changes are:

• Many file types besides HTML can now be displayed
• The two types of configuration files have been consolidated into one and can appear anywhere in target directory
• Most options in configuration files can be given path-specific values; the path can have single (*) or double (**) wildcards. All paths non-absolute are relative to the location of configuration file.

Main arguments

Target directory (path):

This is the directory in which to search HTML content files. It is also the root directory used to infer the website menu hierarchy when use_dir_names = TRUE. The default is the current working directory.

Output directory (output):

The path to where an output directory will be made with a name specified by output_dir_name. The default is the value of the path argument.

Website menu hierarchy options

Displaying content on every page in its menu hierarchy (cumulative):

Currently, intermediate levels in the menu hierarchy cannot be selected, but there are plans to make them clickable. Once that happens, this option will become more relevant.

If TRUE, each pace of HTML content are displayed on every level of its menu classification. For example, if "note_1.html" is assigned to a > b > c and "note_2.html" is assigned to a > b, then the a page and a > b page will display both notes. The default is TRUE.

Using file names (use_file_names):

If TRUE, the names of HTML content files will be used when inferring the menu hierarchy. In other words, the name of the HTML file (minus the ".html") will be in the website menu. The file name can be split using the name_sep option into multiple levels in the menu. See the name_sep documentation for more details. The default is FALSE.

Using directory path names (use_dir_names):

If TRUE, the directory path of HTML content files relative to the target directory (path) will be used when inferring the menu hierarchy. In other words, directory names in the target directory will be in the website menu. The directory names can be split using the name_sep option into multiple levels in the menu. See the name_sep documentation for more details. The default is TRUE.

Splitting file path names by spearator (name_sep):

A character to split directory and file names by before using the information to infer the menu hierarchy. This allows for multiple levels in a hierarchy to be defined in the same directory. This option only has an effect if use_file_names = TRUE or use_dir_names = TRUE. Set to NULL to not split names. The default is -.

Including last part of file name in hierarchy (use_file_suffix):

When a file name is split using name_sep, include the last pace in the menu hierarchy. Only has an effect if use_file_names = TRUE and name_sep != NULL. The default is FALSE.

Including last part of directory path in hierarchy (use_dir_suffix):

When a directory name is split using name_sep, include the last pace in the menu hierarchy. Only has an effect if use_file_names = TRUE and name_sep != NULL. The default is TRUE.

Using configuration for custom placement (use_config_files):

Use configuration files that specify the location of HTML file content in the menu hierarchy. These files must be named as specified by option note_config_name and occur anywhere in the target directory. The default is TRUE.

Specify name of custom placement configuration files (note_config_name):

The name of configuration files anywhere in the target directory that specify the location of HTML file content in the menu hierarchy. The default is ".note.yml".

Specify name of website configuration file (site_config_name):

The name of the configuration file used to provide default option values for this function. If one exists, it should be in the root of the target directory. The default is ".website_config.yml".

Specify a website configuration file (site_config_file):

The path to a build configuration file containing default option values for this function in YAML format. In can also be the path to a directory where a file exists that is named the same as site_config_name. Below is an example of possible content:

clean: false
theme: cosmo
note_config_name: note_config.yml

The default is to look for a configuration file named as specified by option site_config_name in the target directory (argument path).

Modify menu names (menu_name_parser):

This option accepts a function that takes a single character string and returns a single character string. The function specified will be applied to every element in the menu hierarchy. This is useful for removing dates or other ordering prefixes from file names before they are used in the menu hierarchy. For example, to remove a leading number followed by an underscore from every menu name:

quilt(menu_name_parser = function(x) gsub('^[0-9]*_', '', x))

Note that this can cause some changes to where content is displayed. For example, if "1_note.html" and "2_note.html" are parsed using the example function above, they would both appear under the menu element "note" instead of appearing on different pages.

Website appearance options

Bootstrap theme (theme):

The bootstrap theme used in the website. For current options, see the Rmarkdown documentation. At the time of writing, the following themes were available:

• default
• cerulean
• journal
• flatly
• readable
• spacelab
• united
• cosmo

The default is "journal".

Applying theme to embedded HTML content (apply_theme):

If TRUE, apply Bootstrap theme CSS used in the menu to HTML content. The default is FALSE.

Output file structure options

Specify output directory names (output_dir_name):

The name of the output directory made in the location specified by argument ouput containing the website. The default is "website".

Remove intermediate files (clean):

If TRUE, intermediate files in the output directory are deleted after use (e.g. the Rmd files used to make website HTML). This is TRUE by default.

Overwrite previous output (overwrite):

If TRUE, an existing directory with the same name as the output directory will be overwritten. This is FALSE by default to avoid accidental deletions.

WARNING: it is possible to accidentally delete whole directories when overwrite = TRUE. For example, consider the result of trying to output in root (/) when output_dir_name = 'home' and overwrite = TRUE.

Copy entire source directory (partial_copy):

If FALSE, The entire target directory of will be copied instead of just the HTML files and their dependencies. It is possible that more than just the target directory will be copied if there are files in the target directory with dependencies outside it. Enough of the file structure will be copied to included all dependencies. The default is TRUE.

grunwaldlab/quiltr documentation built on May 17, 2019, 8:40 a.m.