While anyone can download and install Tome on a new or existing Drupal site, it works best when used with specific Drupal configurations. This guide will take you from creating a new site to making your first commit.
Before continuing, it’s expected that your local machine has:
- PHP 7 or greater installed.
- SQLite 3.26+
- Composer installed globally.
A global Drush installation is not required to use Tome, but is easier to use than typing “./vendor/bin/drush” every time you want to run a command. This guide will assume that the “drush” command is available.
To start, create a new instance of the starter project by running:
composer create-project drupal-tome/tome-project my_site --stability dev --no-interaction --no-install
cd my_site
composer install
git init
git add .
git commit -m 'Initial commit of starter codebase.'
Optional: This is a good time to install a contributed install profile, for example Bookish which is specially crafted for Tome blogs. You can see a demo of Bookish at https://bookish-drupal.netlify.app to see if it's something you'd like to use. To install Bookish, run "composer require drupal-tome/bookish".
Next you’ll need to initialize your site by choosing an install profile. Run:
drush tome:init
If you don't want to use Bookish, I would recommend using the "Standard" profile when prompted, since it comes with a default theme and content types. If you installed Standard, you will probably want to uninstall the modules that don't make sense for a static site. To do this, run:
drush pmu search history contact -y
If you run “git status” at this point, you should see that the “config” folder is full of exported configuration. You’ll want to commit those changes now so you have a base to work off of in your history. Run:
git add .
git commit -am 'Installed the Standard profile.'
Next you’ll need to start up a local webserver. In a new tab, run:
cd [path to your my_site codebase]
drush runserver 127.0.0.1:8888
Then switch back to your original tab, and run "drush uli -l 127.0.0.1:8888"
A browser window should pop up and log you in as admin.
Now you’re ready to start using Drupal to build you site. Let’s start by adding a new node. Visit http://127.0.0.1:8888/node/add and pick a node type to add (ex: article, blog). Fill out the fields to your liking, and make sure to upload an image.
Once your node has been created, go back to your command line window and run “git status”. You should see that two new files exist in the “content” directory, one for the node you made, and one for the file you uploaded. There should also be a copy of your uploaded file in the “files” directory. Feel free to commit these files now if you’d like.
Tome is always watching your site for changes, and automatically syncs modified config, content, and files as needed. Running “drush tome:export”, which exports everything currently on your site, should be pretty rare after your initial install.
We’re going to test that your site can be fully rebuilt from scratch, to ensure that everything is working properly. Run:
drush tome:install
If you visit your site again, you should see that your node and image as they originally appeared.
Even though your site doesn't have much going on yet, let’s test the static site generation as well. Whenever you’re ready to generate static HTML for your site, run:
drush tome:static
This should put a copy of your site in the “html” directory, which you can then upload to a host of your choosing.
Optional: If you're using Bookish, you'll need to index your search results before running "drush tome:static". For more information, visit /admin/help/topic/bookish_help.tome on your local site to view the related Bookish Help Topic.
That's it for now. You're free to start making your Tome site. Make sure to check out the other documentation, and keep in mind that the project is still in development. Thanks!