In grunwaldlab/quiltr: Automated website creation from scattered HTML

doc_path <- "../inst/doc"
if (file.exists(doc_path)) unlink(doc_path, recursive = TRUE)
dir.create(doc_path)
file.copy(from = "test_website_1", to = doc_path, recursive = TRUE, overwrite = TRUE)
file.copy(from = "test_website_2", to = doc_path, recursive = TRUE, overwrite = TRUE)
file.copy(from = "custom.css", to = doc_path, overwrite = TRUE)

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.

How it works

A single function called quilt is given a target directory containing HTML files and a location to output a website directory. Below is a summary of how it works:

• In the website output directory, a partial copy of the target directory is made, copying only the HTML files and any local files they reference (e.g. image, css, or Java Script links in HTML tag attributes like src and href).
• A menu hierarchy to organize content on the website is inferred from content file paths and/or configuration files, depending on options used.
• Each page of the website (i.e. each location in the menu) is then made. They consists of a hierarchical drop down menu linking to all other pages and a series of iframes used to display HTML files assigned to that page. The iframes are automatically scaled to fit their content.

Together, the partial copy of the target directory (HTML files and their dependencies) and the pages used to display HTML files therein, constitute a portable and self-contained website. If the contents of the target directory change, the function can be run again to update the website. One benefit of this system is that even if a large HTML file appears multiple places on the website, it is only stored once. Also, the original file is available for viewing or download (in Firefox: right click > This frame > ...), which is useful for printing notes or viewing embedded HTML slide shows.

Inferring menu hierarchy

The most useful feature of quiltr is inferring a menu hierarchy from the context of HTML files. There are two general ways to go about doing this:

• using file path/name elements.
• using configuration files to specify custom locations.

Using file path information is probably most appropriate for documenting a computational analysis or research notebook directory since it takes the least upkeep and the organization of the project is evident in the website. Using configuration files can be more involved, but allows for a completely customized hierarchy regardless of the directory or name of HTML content files, making it more appropriate for conventional websites. In any case, the menu can have infinite levels and is mobile-device-friendly.

Using file path information

The placement of HTML content can be determined by the names in its path relative to the target directory. For example, if you had the following 5 HTML files on your computer...

/home/your_name/documents/notes/old/note_1.html
/home/your_name/documents/notes/old/note_2.html
/home/your_name/documents/notes/old/sub_dir/note_3.html
/home/your_name/documents/notes/old/sub_dir/another_sub_dir/note_4.html
/home/your_name/documents/notes/new/note_5.html

...and you specified that the target directory is /home/your_name/documents/notes, then:

• note 1 and 2 would appear together on a page of the website reached by the old menu item
• note 3 would appear on a page accessed by a sub-menu (old > sub_dir)
• note 4 would appear on a page accessed by a sub-menu (old > sub_dir > another_sub_dir)
• note 5 would appear on a page accessed by the menu item new

Which parts of the file path are used and how they are processed is affected by a variety of options. The example showed below corresponds to the default options values, but many variations are possible.

# This is not run automatically due to rmarkdown issue #248, but is used to make the website example
quiltr::quilt(path = "vignette_examples/test_website_1", output = "website_source", overwrite = TRUE, output_dir_name = "test_website_1", theme = "cerulean")

quilt(path = "/home/your_name/documents/notes")

Using content placement configurartion files

Configuration files can be used to specify the location in the menu hierarchy of specific HTML files. This can be used in combination with or independent of the file path information when determining display location. The example below is the same as the previous one except for the addition of two configuration files named ".note_config.yml":

/home/your_name/documents/notes/old/note_1.html
/home/your_name/documents/notes/old/note_2.html
/home/your_name/documents/notes/old/note_config.yml
/home/your_name/documents/notes/old/sub_dir/note_3.html
/home/your_name/documents/notes/old/sub_dir/note_config.yml
/home/your_name/documents/notes/old/sub_dir/another_sub_dir/note_4.html
/home/your_name/documents/notes/new/note_5.html

The name of the configuration files can be specified when building the website, so they can be named anything; in this instance they are named ".note_config.yml". The content of the configuration files should be a named list in YAML format, where the name is a file path relative to the configuration files' location and the elements of the list are website menu locations. The file path can include wildcards or other common file path syntax. The configuration files listed above in the example have the following content:

/home/your_name/documents/notes/old/note_config.yml:

cat(readChar("../vignette_examples/test_website_2/old/note_config.yml", nchars = 10000))

/home/your_name/documents/notes/old/sub_dir/note_config.yml:

cat(readChar("../vignette_examples/test_website_2/old/sub_dir/note_config.yml", nchars = 10000))

The first configuration file causes the content of "note_1.html" to be displayed in the menu location custom > placement instead of old. The second has two effects:

• The the levels relative > placement are added to the menu location that "note_3.html" is displayed under. The . as the first list element causes the following levels to be added to the menu path instead of replacing it. The location in the hierarchy is therefore old > sub_dir > relative > placement.
• All HTML files in any sub directory (relative to /home/your_name/documents/notes/old/sub_dir) will not be included in the website due to NULL being the only element specified. In this case, "note_4.html" will not be included.

Below is the result of building the above directory structure using default options:

# This is not run automatically due to rmarkdown issue #248, but is used to make the website example
quiltr::quilt(path = "vignette_examples/test_website_2", output = "website_source", overwrite = TRUE, output_dir_name = "test_website_2", note_config_name = "note_config.yml", theme = "cerulean")

quilt(path = "/home/your_name/documents/notes", note_config_name = "note_config.yml")

Using a website build configuration file

In addition to the configuration files used to determine content location, there is another type used to specify default website building options. This configuration file is also in YAML format and contains the values of some or all of the options accepted by the quilt function. Option values specified here replace the defaults when running quilt, although options specified in the configuration file can still be overwritten by function options used. Unlike the content placement configuration files, only one of this type of this type can be used each time a website is built. They are useful for storing the options used to build a specific website in its source directory so that rebuilding the website can be simplified to running quilt() in the project directory. Below is an example of website build configuration file content. In the context of the previous examples, this configuration file would be saved at "/home/your_name/documents/notes/build_config.yml".

clean: false
theme: cosmo
note_config_name: note_config.yml

In addition to the user generated files in the source directory, these type of files are automatically made in the output each time a website is created to record the parameters used. Since the configuration file used can be specified by a quilt option, these can be referenced to rebuild a website with the same parameters as last time.

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