Academic Labbook Plugin, or ALP for short, requires an up-to-date version of WordPress. Installation comes in two parts: the plugin and the theme. The plugin adds the core functionality to WordPress, and the theme displays the customisations. You must upload two zip files using the administration dashboard. Eventually it might be possible to install the plugin via the WordPress Plugin Directory.

If you have not yet installed WordPress, do so now. You should understand the difference between a single site and a multisite WordPress installation. It is usually appropriate to use ALP with a multisite WordPress installation in academic contexts, so you can easily create new blogs for new experiments. If you wish to use WordPress in multisite mode, there are a few extra configuration steps required.

Terminology

“Network” refers to a WordPress multisite installation. There are a few steps in this guide which are only relevant to networks and involve performing steps within the network admin dashboard. If you have configured a network, any steps which must be performed on an individual blog (which is most of them) must be performed to each blog on your network. If you have only configured a single site, then you can ignore any network-only steps.

Guide

First we’ll get the latest plugin and theme installation files. Grab the latest Academic Labbook Plugin zip from GitHub. Note: you should download the “ssl-alp-x.x.x.zip” file from the “Assets” section below the changelog on the latest release, not tag. Releases can be distinguished from their larger titles saying “Academic Labbook Plugin x.x.x”. Do not download the “Source code” zip, as this will not install correctly.

Now we’ll install the plugin. If you are on a network installation, go to the network plugin page. If you are on a single site, go to the standard blog plugin page. Click “Add New”, then “Upload Plugin”, and specify the zip file you downloaded and click “Install Now”. If all goes well, it will install, but it won’t activate itself. You should click “activate”. On a network, you should network activate the plugin to get the most out of it (this means it is automatically enabled on all current and future blogs on the network, and enables a few extra features like the ability to specify extra upload media types).

Next, we’ll install the theme. Grab the latest Labbook theme zip from GitHub (remember: get the “labbook-x.x.x.zip” file from the “Assets” section below the changelog on the latest release, not tag). If you are on a network, go to the network theme page. If you are on a single site, go to the standard blog theme page (under Appearance). Click “Add New”, then “Upload Theme”, then specify the file and click “Install Now”. As with the plugin, you should either network activate or activate the theme on your single site depending on your configuration.

You should also visit your site (or each blog on your network in turn) and enable the theme using the Appearance -> Themes page, as merely installing the theme does not enable its appearance on the front end until you do this.

After installation

There are some important extra steps after installation that ensure everything is properly configured. You can also just jump right into using the site at this point, but it’s not recommended.

Rebuild coauthor terms

Visit the Tools -> Academic Labbook page and rebuild the coauthor terms. This makes all of the users registered on your blog able to be selected as coauthors in the New Post screen.

This step is not automated because WordPress has no reliable way of doing this during plugin activation.

If you run a network, you should rebuild coauthor terms on each of your blogs. If you just set up a new network, you should only have one.

Configure plugin and site settings

In the Settings -> Academic Labbook page, configure the plugin settings as you wish. Next visit the Tools -> Academic Labbook page again, and read the Optimise core WordPress settings for private labbook section. If you wish, you can use this tool to quickly configure a bunch of the built-in WordPress settings as appropriate for an academic labbook. Note that this tool is only available if you have kept the site private (set using the Settings -> Academic Labbook page).

On networks, you may also wish to set WordPress’s maximum upload file sizes, etc. in the main network settings page.

Convert user roles

WordPress is normally used for commercial blogs, so its built-in user roles are appropriate for that kind of site: editors (can edit everything), authors (can only edit their own stuff), subscribers (can comment but not edit or create new stuff), etc. In the academic context, however, it’s best to change these. ALP has a tool to automatically reconfigure the built-in roles appropriately.

Visit the Tools -> Academic Labbook page. Read and understand the Convert user roles section. If you are happy to make these irreversible changes, tick the box and click the button.

After changing user roles, you may wish to set the default user role to be assigned to new users in Settings -> General.

Set custom KaTeX script paths (optional)

This only applies to networks.

For whatever reason, if you wish to use different URLs to host the JavaScript and CSS scripts required for mathematical rendering, set these in the Academic Labbook settings page in the Network Admin settings panel.

Add additional upload media types (optional)

This only applies to networks.

It is likely that your users will want to upload files which are not allowed by standard WordPress. ALP lets you specify additional media (also known as “MIME”) types which are allowed to be uploaded. Visit the Academic Labbook settings page in the Network Admin settings panel to add these. You can find a list of common media types here.

Configure theme settings

You can upload a logo, change the description, enable or disable revisions and tables of contents, etc., using the Customiser. While logged in as an admin, click the “Customise” link on the bar at the top, and play around until you are happy.

Getting help

Installation is supposed to be quite straightforward, and setting descriptions clear. If you need help, please feel free to get in touch.