Drupal 8 as a Static Site: The Tome Module

Submitted by nigel on Wednesday 31st October 2018

There are many ways to generate html content, and wget and curl are two contenders. But there's an easier way with Drupal 8 - the Tome module which is documented here

I won't reproduce the Tome manual here, Instead let's get the Tome module installed and take a look around. 

Install and Enable Tome Module
$ composer require drupal/tome
<--snipped-->
  - Installing drupal/tome (1.0.0-alpha2): Downloading (100%) 
$ drush en tome -y
The following extensions will be enabled: tome, serialization
Do you really want to continue? (y/n): y
serialization was enabled successfully.                                                                             [ok]
tome was enabled successfully.                                                                                      [ok]
Install Tome Drush
Tome's drush commands require drush 9 so I needed to update my drush from 8 before I could continue.
$ composer require  drush/drush:9.*
<--snipped-->
  - Updating drush/drush (8.1.15 => 9.5.2): Loading from cache
Ok so now we can install Tome's drush commands.
$ composer require drupal-tome/tome_drush
<--snipped-->
  - Installing drupal-tome/tome_drush (dev-master f0d6441): Cloning f0d6441879 from cache
<code>
Configure Tome
Let's start off with a basic configuration which we can refine and fine tune as we go along. The configuration is held in settings.php, or in my case settings.local.php.
settings.local.php
<?php
/**
 * Tome Settings
 */
$tome_base_path '..'.DIRECTORY_SEPARATOR.'static';
$settings['tome_static_directory'] = $tome_base_path.DIRECTORY_SEPARATOR.'html';
$settings['tome_content_directory'] = $tome_base_path.DIRECTORY_SEPARATOR.'content';
$settings['tome_files_directory'] = $tome_base_path.DIRECTORY_SEPARATOR.'files';
$settings['tome_book_outline_directory'] = $tome_base_path.DIRECTORY_SEPARATOR.'extra';
?>
The settings should be self-explanatory, and I have elected for an approach where everything goes beneath an overarching static directory.
Creation of Static Pages
Ok we are now ready to create the static pages. A bit of a voyage of discovery - let's see what happens!
$ drush tome:static --uri badzilla.co.uk
 
 // CSS and JS preprocessing is disabled. This could lead to performance issues. To resolve, visit                      
 // /admin/config/development/performance.                                                                              
 //                                                                                                                     
 // To suppress these messages, pass the --ignore-warnings option.                                                      
 
Generating static HTML...
 220/220 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 33/33 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 21/21 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 4/4 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 2/2 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
Processing related assets and paths...
 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%
 
 
 [OK] Exported static HTML and related assets.                                                                          
 
The Output

The tome:static interrogates Drupal and creates a list of all known paths that are accessible to anonymous traffic. From these it generates the html for each page and this is placed in the tome_static_directory. Tome creates a directory per Drupal route, the directory name being the route url which has been either created by the content author or generated by pathauto. Inside each directory is a file named index.html. The only draw back of this, which is a very minor inconvenience, is browsers display pages with a forward slash at the end of each url.

Views are handled similarly, although the scheme is extended to the creation of a page subdirectory so pagination can be handled. Underneath this subdirectory is a numeric sequence representing each page in the paginator's sequence. See below.

My blog view in static files.
$ ls blog
index.html  page
$ cd blog
$ find .
.
./page
./page/9
./page/9/index.html
./page/11
./page/11/index.html
./page/7
./page/7/index.html
./page/6
./page/6/index.html
./page/10
./page/10/index.html
./page/8
./page/8/index.html
./page/4
./page/4/index.html
./page/3
./page/3/index.html
./page/12
./page/12/index.html
./page/2
./page/2/index.html
./page/13
./page/13/index.html
./page/5
./page/5/index.html
./page/14
./page/14/index.html
./index.html
This results in for example a url like /blog/page/2/
Spin up a webserver to eyeball the static site
default

To check whether everything is working ok, we need to eyeball our site and see if there are any problems. We need a webserver to achieve this. We could have added the runtime switch --run-server to the tome:static command. The other option is to create our own webserver - I provide the configuration for doing this in the next chapter. 

Note that to generate the static files I used the --url badzilla.co.uk parameter. This is crucial because without it, Drupal has no idea how to populate $base_url. Referring to the screenshot above from the generated home page, all those ringed badzilla.co.uk uris, such as in the canonical link and the schema JSON-LD, would actually be default without this. To be avoided! 

Problem Areas

I was astounded how well the static site was created. Navigating around pages, inclusion of JS and CSS was flawless. There were a few problems which needed addressing though. In a subsequent chapter we'll look at these in detail.