Github pages is a free hosting service provided by Github, intended to be used for open source project documentation and simple, non-commercial sites. This document will go over the basics of using Tome for your (github.io) homepage, or in a sub-directory.
Using Tome as your github.io homepage
Every Github user and organization can have a *.github.io homepage hosted with Github pages. The website you're looking at is hosted at drupal-tome.github.io and exists in the drupal-tome/drupal-tome.github.io repository.
To set up your own homepage, create a repository in the format [user/org name].github.io at https://github.com/new.
Once this is done, we'll need to initialize Tome in this repository. Run:
composer create-project drupal-tome/tome-project <repository name> --stability dev --no-interaction --no-install
cd <repository name>
composer install
git init
git checkout -b dev
git add .
git commit -m 'Initial commit of starter codebase.'
git remote add origin <repository URL>
git push -u origin dev
You may be wondering why we're using the "dev" branch instead of "master" - github.io homepages are a bit different from other Github pages repositories and expect all HTML to exist in the "master" branch.
Now you'll probably want to use Tome locally for a bit and create content. Run:
drush tome:init
# Follow prompts to choose a profile.
drush runserver 127.0.0.1:8888
drush uli -l 127.0.0.1:8888
# Follow link to login as admin and use Drupal.
Once you're happy with your changes, do another git commit and push your changes up to dev again.
Now we're ready to generate your static site! Run:
drush tome:static -l https://<github.io domain>
You should now have a "html" folder in the root of your repository. Now we need to get this into the "master" branch of your repository - a lot of smart people online have done clever things with Git to make this work, but I prefer something more dumb and readable. Run:
rm -rf gh-pages
git clone [email protected]:drupal-tome/drupal-tome.github.io.git gh-pages
cd gh-pages
git checkout master || git checkout -b master
cd ..
rm -rf gh-pages/*
cp -r html/* gh-pages/
cd gh-pages
git add .
git commit -m 'Updating gh-pages site'
git push -u origin master
For this site, I made this a script that I can run with Composer, so every time I want to generate and publish my static site, I just run "composer gh-pages". You can see what I did by visiting the drupal-tome/drupal-tome.github.io repository. I'd recommend that most Tome sites implement a similar build and publish script.
So now, if everything went right, you should see your Tome site on your github.io domain!
Using Tome for a project sub-page
Github pages also allows users to create sites per-repository, which are accessible as a sub-directory of your main github.io domain. If you want to use Tome for a project page, follow the instructions above, keeping in mind these changes:
1. You can use the "master" branch instead of "dev" as your main branch.
2. Make sure to build the static site with a base URL that includes the sub-directory:
drush tome:static -l https://<github.io domain>/<project-name>
This will result in your index.html file existing in the "html/<project-name>" folder.
3. When running the "dumb and readable" commands above, replace "master" with "gh-pages", and replace "cp -r html/* gh-pages/" with "cp -r html/<project-name>/* gh-pages/". While Github will serve your project page from a sub-directory, it expects your "gh-pages" branch to contain a top-level index.html file.
If you want an example sub-page to reference, you can visit the example project at https://tome.fyi/subdir-test and its source at drupal-tome/subdir-test.