Overview
Static sites typically only contain plain HTML, CSS, images, and possibly a bit of JavaScript.
This guide focuses on how to use the Tome Drupal module to generate a static version of any basic Drupal website.
Why can only basic Drupal sites be turned into static sites?
By definition, static sites do not run any server side code, so standard form submits, user logins, AJAX interaction and communication with REST APIs are NOT supported. This means no Drupal forms / webforms, no views with complex filters (though some filtering can be supported), no user-based customisation of any kind.
This also means reactive front-end frameworks like React, Vue, or HTMX are NOT supported either.
In this guide we'll cover all the Drupal goodness that is supported out of the box, as well as how to generate and review a static site locally.
Our ongoing mission: to seek out new modules and new ways of supporting more Drupal functionality through contributed modules. To boldly go where no static Drupal site has gone before.
For more in-depth information about Tome, see https://tomy.fyi/docs.
Tome Static: a Static Site Generator
Toughly speaking, the Tome module is split into two separate components: Tome Sync and Tome Static.
- Tome Sync, though certainly interesting, is not directly relevant to static site generation, so we will NOT be discussing it in this guide.
- Tome Static is the engine that turns Drupal sites into static sites. For the rest of this guide we'll refer to Tome Static simply as "Tome".
How Tome works
Tome's approach to static site generation is quite straightforward:
- Tome builds a list of all paths (nodes, views, RSS feeds, ...) accessible to anonymous users.
- For each of those paths, Tome exports a fully rendered, static version and saves it as an HTML page.
Website URLS and static site paths
To fully understand the exported structure of your static site, you first need to understand how (static) website paths work.
In its most basic form, the URL to any given web page will be something like: https://example.com/about.html.
This URL refers to a physical file named about.html, located in a specific directory (refered to as the document root or docroot) tied to the example.com domain name.
Conversly, when you're requesting, say, https://example.com/about/family.html, you're actually looking at the family.html file in the /about/ directory, which in turn sits in the document root directory.
The DirectoryIndex file
However, when you browse to, say, https://example.com, you also see content. So which file are you looking at?
If no specific file is mentioned in the URL, you're looking at whichever file is configured as the DirectoryIndex file, which is typically index.htm, index.html, or index.php.
Let me repeat that: if you request https://example.com, you're actually looking at https://example.com/index.html.
Stay with me, all of this is important.
Drupal paths and path aliases
Say you have a node with path /node/123 and path alias /content/my-page.
To make both paths available, Tome will have to generate:
- A directory
/node/123/which contains fileindex.html
(full path:/node/123/index.html) - A directory
/content/mypage/which contains fileindex.html
(full path:/content/mypage/index.html)
Of course, both of these index.html files will be identical... it's the same piece of content being exported.
In other words, when Tome generates your static site, you can expect:
- A
/node/<node id>/directory for each exported node. - A directory (possibly with sub-directories) for each path alias.
Next steps
Ok, with this intro and directory structure theory out of the way, time to generate a static site!